mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 16:29:42 +01:00
170e1b0c078d0db64cf3deadd4d5f21e86d7fdcf
2647
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
170e1b0c07 |
feat(runner): pin Codex 0.170.0 and Agent SDK 0.3.328 so Fable 5.2 and GPT-6.2 run (#22278)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip Runner runs Claude and Codex agents from one shared provider pack. The pack pins an exact Claude Agent SDK (which bundles Claude Code) and an exact Codex CLI. > - #22222 added Claude Fable 5.2 (minimum Claude Code 2.1.321) and GPT-6.2 Sol and Astra (minimum Codex 0.169.1). The pack still bundles Claude Code 2.1.286 and Codex 0.160.0. > - Because of this, Paperclip Runner stops these models with a named version error, and native remote Codex accepts only `>=0.149.0 <0.161.0`. > - This pull request moves the provider pack to Agent SDK 0.3.328 (Claude Code 2.1.328) and Codex 0.170.0. It moves every constant that depends on these pins, and the remote Codex window to `<0.171.0`. > - The benefit is that Fable 5.2 and GPT-6.2 run on Paperclip Runner after a sandbox image with this pack is promoted. ## Linked Issues or Issue Description Refs #22222 (adds the models and the version floors; this pull request makes them runnable on Paperclip Runner). Refs #18488 (moves only the Codex pin to 0.166.0 and the window to `<0.167.0`; it is not updated since November 1 and has conflicts with `master`). Refs #18486 (GPT-6.1 Terra needs Codex 0.165.0; Codex 0.170.0 satisfies it). **Overlap with #18488.** #18488 changes the same Codex pin locations. This pull request uses a newer pin (0.170.0) and also moves the Claude runtime. If this pull request merges first, #18488 has no remaining change. I did not change the #18488 branch. ## What Changed - Claude runtime: `@anthropic-ai/claude-agent-sdk` 0.3.286 → 0.3.328 (Claude Code 2.1.286 → 2.1.328). This changes the root `pnpm.overrides`, `pnpm-workspace.yaml`, the ACPX `claude` profile, and the qualified Claude runtime in `installation-integrity.ts`, with new executable digests for Linux x64, Linux ARM64, macOS ARM64, and macOS x64. - Codex runtime: `@openai/codex` 0.160.0 → 0.170.0. This changes the runner dependency, the `codex-acp@1.6.2>@openai/codex` override, the `codex-acp` patch dependency line, the ACPX `codex` profile, and the qualified Linux x64 runtime with its new executable digest. - The ACP bridges do not change: `claude-agent-acp` 0.73.0 and the patched `codex-acp` 1.6.2. Their `commandDigest` values and profile versions do not change. - Generated declarations: `generated-profiles.ts` and `generated_acpx_profiles.rs` are regenerated with `generate:acpx-profiles`. - Remote native Codex window: `REMOTE_CODEX_MAXIMUM_VERSION_EXCLUSIVE` 0.161.0 → 0.171.0. The minimum stays at 0.149.0. Images with Codex 0.149.0 through 0.170.x are accepted. - Codex company observability: the qualified-version check moves to `codex-cli 0.170.0`. The `otel` configuration keys that Paperclip writes (`exporter`, `trace_exporter`, `metrics_exporter`) are present in the 0.170.0 configuration schema. The `OtelExporterKind`, `OtelHttpProtocol`, and `OtelTlsConfig` definitions are identical to 0.160.0. - Daytona runner image probes (`Dockerfile`, `Dockerfile.release`) expect `codex-cli 0.170.0` and `2.1.328 (Claude Code)`. The remote npm install spec in `server/src/adapters/registry.ts` is `@openai/codex@0.170.0`. - Tests: fixtures and assertions that mirror the pins use the new versions. The window tests accept 0.161.0 through 0.170.99 and reject 0.171.0. The ACPX gate tests now show that Fable 5.2 and GPT-6.2 are admitted. A new test mocks an older bundled runtime and keeps the named version-gap errors covered. The fallback test shows that GPT-6.2 stays on 0.170.0 and still falls back on 0.160.0. - Opt-in qualification scripts (`scripts/tests/native-cleanup-paginated-codex.mjs`, `native-provider-startup-codex.mjs`) require Codex 0.170.0. - Documentation: `docker/daytona-runner/README.md`, `doc/architecture/paperclip-runner-compatibility.md`, `doc/agent-observability.md`, `docs/deploy/environment-variables.md`, and the deferred item in `doc/adapter-model-audit-2026-11-18.md`. - `pnpm-lock.yaml` is not part of this pull request. The refresh bot regenerates it on `master`, as for the previous pin refreshes (#14942, #14993). ## Verification Sources, checked on 2026-11-19: - npm registry: `@openai/codex@0.170.0` (published 2026-11-18T03:45Z) and `@anthropic-ai/claude-agent-sdk@0.3.328` (published 2026-11-18T23:13Z, `claudeCodeVersion` 2.1.328). Both are the `latest` tags. - [Codex releases](https://github.com/openai/codex/releases) 0.161.0 through 0.170.0. The notes record no app-server protocol break. 0.169.0 keeps project configuration disabled for `codex exec` in untrusted directories; Paperclip's CLI path already uses `--skip-git-repo-check`, and the native path uses `app-server`. - [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) 2.1.287 through 2.1.328. See "Risks" for the headless changes that I reviewed. Digests and package shape: - I downloaded each platform archive with `npm pack`, which verifies registry integrity, and computed the SHA-256 of the executable. As a method check, the same command on the 0.3.286 Linux x64 archive gives the digest that is on `master` (`fe503f65…`). The Codex 0.160.0 archive also gives the `master` digest (`12eb3e81…`). - The extracted executables report `codex-cli 0.170.0` and `2.1.328 (Claude Code)`. - The Codex 0.170.0 Linux x64 archive no longer contains `codex-resources/zsh/bin/zsh`. Paperclip does not reference that path. - The Agent SDK 0.3.328 `optionalDependencies` have the same platform set as 0.3.286. The Codex 0.170.0 `optionalDependencies` use the same `npm:@openai/codex@<version>-<platform>` aliases. - Bridge link check: I installed `@agentclientprotocol/claude-agent-acp@0.73.0` with an override to Agent SDK 0.3.328 and imported its entry module. Node linked all of the named SDK imports, and the import completed. Real Codex qualification (no model turn, no credentials): - `PAPERCLIP_TEST_CODEX_BINARY=<installed 0.170.0 Linux x64 binary> node --import ./server/node_modules/tsx/dist/loader.mjs scripts/tests/native-cleanup-paginated-codex.mjs` passed: `green: true`, with the expected red control and paginated `thread/resume` through the real 0.170.0 `app-server`. The installed binary digest matches the pinned digest. Focused suites (Linux x64, Node 25.9.0, local `pnpm install --no-frozen-lockfile`): - `cd packages/paperclip-runner && pnpm run typecheck:typescript` passed, including `check:acpx-profiles`. - `npx tsc --noEmit` passed in `packages/adapters/codex-local` and `packages/adapters/claude-local`. - `packages/adapters/codex-local`: 625 passed. `packages/adapters/claude-local`: 419 passed, 1 skipped. - `node --test`: `acpx-codex-package-contract` 9 passed, `controlled-evals/controller` 77 passed, `scripts/acpx-patch-packaging` 26 passed, `scripts/__tests__/grok-public-install-sandbox` 27 passed. - `server`: `acpx-qualification`, `codex-runtime-compatibility`, and `codex-model-fallback` 110 passed. `native-session-executor` 1541 passed, 1 failed. The failure (`compares export process compatibility … db.transaction is not a function`) also fails on unchanged `master` on this host. - `packages/paperclip-runner` vitest (`installation-integrity`, `qualified-profiles`, `codex-security-config`, `native-execution`, `native-backend-factory`): 283 passed, 25 failed. All 25 failures are in `installation-integrity.test.ts` with "ACPX provider lifetime guardian failed to start". The same 25 tests fail on unchanged `master` on this host (master fails 30 here). Rust (toolchain 1.97.1 from `rust-toolchain.toml`, Linux x64): - `cargo test -p paperclip-runner-core --lib`: 658 passed, 2 failed, 4 ignored. `warm_run_attachment_reuses_the_provider_ingress_listener` also fails on unchanged `master` on this host. `reaping_stops_a_dead_runners_provider_and_its_escaped_tool_job` is flaky here: on this branch it passed 2 of 3 reruns. - `cargo test -p paperclip-runner-core --test acpx_warm_attachment --test native_provider_backend`: 7 and 45 passed. - The new and changed saved-session tests pass: `a_session_saved_by_the_previous_agent_runtime_is_refused_by_name`, `unrestorable_saved_sessions_keep_strict_bindings_and_name_their_class`, and `a_settled_session_saved_by_the_previous_acpx_release_continues`. `rustfmt --check` passes. - `server`: `native-session-resume.test.ts` and `acpx-qualification.test.ts` 110 passed, 2 skipped. Both new resume cases run and pass. Not run here: - `native-provider-startup-codex.mjs`, because it needs a compiled `paperclip-runnerd`. The trusted CI runner workflow covers startup and session-resume probes. - The Docker image build and any live model turn. A live Fable 5.2 and GPT-6.2 test follows the staging image rollout. ## Saved sessions from the previous release This change keeps the ACPX bridge command digests and profile versions. It changes `agentRuntimeVersion` in the `claude` and `codex` ACPX profiles. That field is part of the saved session identity. The previous release saved sessions with Agent SDK 0.3.286 or Codex 0.160.0. This build refuses those saved sessions. It does not migrate them. - **Next run (the usual case):** the saved provider descriptor names the old runtime. `rebindNativeSessionCheckpoint` does not match it, so the next run starts a fresh provider session in the same workspace with the complete handoff prompt. No run fails. The earlier provider conversation does not carry over. - **A run in flight at the deploy (settled or mid-turn):** the runner restore refuses the saved descriptor with the permanent class `provider_state_incompatible`. The server reports it as `native_provider_state_incompatible` and stops automatic retries. The runner opens no provider and keeps the saved state bytes and the workspace. The next run on the task starts a fresh provider session. - **Native Codex (`codex_app_server`) and OpenCode** sessions do not record this field, so their resume decision does not change. After a new image is promoted, native Codex resumes a saved thread with Codex 0.170.0 instead of 0.160.0. This pull request does not test that cross-version thread resume. New tests: - `acpx_provider_backend.rs`: `a_session_saved_by_the_previous_agent_runtime_is_refused_by_name` covers settled Claude and Codex sessions and a Claude turn interrupted mid-run by the deploy. `unrestorable_saved_sessions_keep_strict_bindings_and_name_their_class` has a new `agent_runtime_release` case. Each case checks the named class, that no provider session opens, and that the saved bytes do not change. - `native-session-resume.test.ts`: "a session saved by the previous Claude or Codex ACPX runtime" checks that a same-release session resumes, and that a session saved with Agent SDK 0.3.286 or Codex 0.160.0 starts fresh in the same workspace. ## Risks - Medium. Every Paperclip Runner Claude and Codex run uses the new executables. The digests, generated profiles, image probes, and window must agree. They agree locally, and CI runs the Rust and runner suites again. - Claude Code 2.1.287 through 2.1.328 change some headless defaults. I checked each one against Paperclip: - 2.1.302: `-p` and Agent SDK sessions with no permission mode start in `default` mode on third-party providers. Paperclip always sets a mode (`bypassPermissions` or `default`), so this does not apply. - 2.1.299: MCP allow rules now match only the whole server name. Paperclip already writes `mcp__<server>__*` and exact `mcp__paperclip__<tool>` rules. - 2.1.302: fork subagents are on by default in `-p` and the Agent SDK, as in the terminal. This pull request keeps the upstream default and does not set `CLAUDE_CODE_FORK_SUBAGENT=0`. Reviewers can ask to keep them off. - 2.1.299 and later: stdio MCP connections negotiate MCP protocol 2026-07-28 first and fall back to the older protocol for servers that do not answer. - Agent SDK 0.3.328 is less than one day old. If a regression appears, revert this pull request to return to 0.3.286 and Codex 0.160.0. - Sandbox images built before this change still carry Codex 0.160.0 and Claude Code 2.1.286. They stay accepted. On those images, Fable 5.2 and GPT-6.2 keep the existing named errors and fallbacks until a new image is promoted. - Until the refresh bot updates `pnpm-lock.yaml` on `master`, a local `--frozen-lockfile` install fails, as with the previous pin refreshes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude, model ID `claude-opus-5-5`, through Claude Code with tool use (shell, file edit, `gh`) and code execution. The context window and reasoning mode are not reported in this session. - The registry archives, digests, release notes, configuration schemas, and changelog were read directly. No model output was used as a source for those facts. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
1dba97303e |
fix(runner): wait for run.attach before restoring a Codex session on a fresh Runner (#22267)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Runnerd runs a coding harness such as Codex or Claude (through ACPX) for one agent session, and keeps durable state so a later run can continue the conversation > - Core can rotate a session to a new run before it starts the Runner. It archives the old Runner state and starts a Runner under the new run's identity, over the same saved provider session > - ACPX waits for `run.attach` in this case. Codex does not: if the saved session was still open, Codex restores the app server on the first poll or command, with the old run's settings > - This pull request makes Codex follow the ACPX rule > - The benefit is one app-server start with the new run's settings, and no old-session events in the new run before attachment ## Linked Issues or Issue Description **What existing behavior does this improve?** A Runner that starts with fresh durable state over a saved, open Codex session. **Subsystem affected** Runnerd: the durable runner and the Codex provider executor. **Current behavior** The Codex executor restores the app server on the first poll or command. It uses the saved run's tools and settings. Restore events go out under the new run before `run.attach`. If `run.attach` changes the tool set, the app server restarts, so it starts twice. **Proposed behavior** The Codex executor waits for `run.attach` before it restores. Until then it refuses commands that start work; snapshots and shutdown commands still work. The wait is saved with the Codex state, so a restart before attachment keeps it. `run.attach` treats the saved open session like a stopped session, so the app server starts once with the new run's settings. A Runner that recovers its own durable state restores as before. **Reason and benefit** All providers then use one rule for a Runner that starts as a new run. Today this case occurs only after a rotation from a lost Runner or from a session left open. A later change can use the same rotation for every follow-up that starts a new Runner process. ## What Changed - Before it creates fresh durable state, the durable runner tells the executor (`observe_fresh_durable_state`). - The native executor then marks a saved Codex session as waiting for `run.attach`. The Codex executor reads the mark when it loads the session. - The Codex executor does not restore the provider until attachment, and refuses commands that start work. Snapshot, close, drain, suspend, shutdown, interrupt, cancel and stop still pass. - The mark (`awaitingRunAttach`) is saved before the Runner's durable state exists, so a Runner lost or restarted before `run.attach` keeps waiting. `run.attach` clears it. `run.attach` accepts a saved `session_open` or `provider_exited` session without a live provider, the same as a stopped (`prepared`) session. - `DURABLE_TRANSPORT.md` describes the rule. - Four tests: a fresh Runner waits for `run.attach` and starts Codex once; a restart before attachment still waits; a Runner lost right after a fresh start still waits; a recovered Runner still restores its own session. ## Verification - `cargo test -p paperclip-runner-core --test codex_provider --test native_provider_backend --test durable_recovery`: 131, 47 and 4 passed. - `npx vitest run src/live/runnerd-codex-transport.test.ts` in `packages/paperclip-runner`, with a rebuilt runnerd: 335 passed, including the removed-context rotation. - `cargo test -p paperclip-runner-core --lib durable::`: 133 passed. - Red-green: with the fence turned off, `a_fresh_runner_waits_for_run_attach_before_restoring_a_saved_session` fails on the first poll. Without the saved wait, `a_fresh_runner_restarted_before_run_attach_still_waits_for_it` fails. - `cargo fmt --all -- --check` passes. ## Risks - Low risk. The fence applies only when the durable state is fresh and a saved Codex session exists. New sessions have no saved session. Recovered Runners do not get the fence. - While the fence is set, the Runner refuses commands that start work. Core sends `run.attach` first after a rotation, so no current flow is blocked. Teardown commands still pass, so a session whose `run.attach` fails can still close. - The new state field is omitted when false, and older Runners ignore it. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use (code search, editing, local test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
067f7a0815 |
feat(telemetry): send product lifecycle events and agent run failure cause (#22250)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - First-party telemetry tells the team which product steps people finish > - Telemetry did not record when a model is connected, when a task is created, completed, or blocked, when a plan is created or approved, or when an artifact is created > - Telemetry also did not tell why an agent run failed, so failures could not be grouped by cause > - This pull request syncs the new telemetry contract and sends these events from the server once per real change > - The benefit is a product funnel and a failure breakdown that use only enums, booleans, and counts ## Linked Issues or Issue Description **Subsystem affected** Server telemetry (`packages/shared/src/telemetry`, `server/src/services/product-telemetry.ts`) and the emit sites in the issue, document, work product, interaction, and AI connection services. **Problem or motivation** The team cannot measure the main product path. There is no event for a new model connection, a new task, a completed task, a blocked task, a new plan, an approved plan, or a new artifact. `agent.task_run` tells that a run failed, but not why. The signup funnel also must know when the onboarding wizard created the first task. **Proposed solution** Register the events in the telemetry backend. Sync the generated contract here. Add typed helpers. Send each event once, after the transaction that makes the change commits. Use fixed enums for every kind, reason, and cause. **Alternatives considered** A post-commit action queue on the issue service only. The native status path and many other callers use an external transaction without that queue, so most agent completions would not send an event. A generic after-commit hook on the database client covers every caller. **Roadmap alignment** This is telemetry for existing features. It adds no new product feature. **Additional context** This change depends on paperclipai/telemetry-backend#150, which is merged. Deploy that backend change before this change ships. Until then, the collector rejects the new event names. ## What Changed - Sync `generated/paperclip-telemetry.ts` from the backend branch as a direct copy. Regenerate `posthog-direct/enum-fallbacks.generated.ts` with `scripts/generate-posthog-direct-fixtures.mjs`. The loader golden file did not change. - Add `afterTransactionCommit()` to `@paperclipai/db`. It runs a callback after the outermost transaction commits. It drops the callback on rollback. Outside a transaction it runs the callback at once. A callback that throws never fails the committed work. - Add helpers `trackModelConnected`, `trackTaskCreated`, `trackTaskCompleted`, `trackTaskBlocked`, `trackPlanCreated`, `trackPlanApproved`, and `trackArtifactCreated`. Add `failureCause` to `trackAgentTaskRun`. Assign the new events to `operational_enum_count` retention. - Add `server/src/services/product-telemetry.ts`. It sends each event after commit inside `withTelemetryCompany()`, so Cloud direct delivery gets `company_id` for background writes. - Emit sites: - `model.connected`: `aiConnectionService.save`, for a new connection only. A reconnect sends nothing. `first_for_company` is true when the company had no earlier model connection. - `task.created`: `issueService.create`, after the insert. A deduplicated create, a company import, and a chat conversation send nothing. `created_by_kind` is `routine` for routine runs, `onboarding` for the onboarding wizard's first task, and otherwise `user`, `agent`, or `system`. - `task.completed` and `task.blocked`: `issueService.update`, when the status changes to `done` or `blocked`. The same status again sends nothing. - `plan.created`: `documentService.upsertIssueDocument`, for the first revision of the `plan` document. - `plan.approved`: the accept path of a `request_confirmation` that targets the task's `plan` document. - `artifact.created`: `workProductService.createForIssue` (`direct`), the promotion route (`promotion`), and a run file deliverable (`run_deliverable`). - `agent.task_run.failure_cause`: `emitAgentTaskRun`, for `failed`, `timed_out`, and `interrupted` runs only. - `blocked_reason` mapping: unfinished blocking tasks give `waiting_on_task`. Otherwise an unblock owner of a person or the board gives `waiting_for_person`, and an agent owner gives `waiting_for_agent`. A system write with neither gives `needs_recovery`. A person or agent write with neither gives `unspecified`. - `failure_cause` mapping (stored `errorCode`, with `resultJson.providerFailure.category` for generic provider and adapter codes): - `missing_access`: auth and permission codes (`acpx_auth_required`, `provider_auth_failed`, `user_secret_missing`, `github_access_denied`, `github_repo_not_accessible`, `permission_denied`, `project_access_denied`, `configuration_incomplete`, `connection_unavailable`, `signing_secret_unconfigured`), and provider category `authentication` or `permission`. - `provider_limit`: `provider_quota`, `native_provider_usage_limit`, `native_provider_overloaded`, `github_rate_limited`, `ai_connection_busy`, and provider category `rate_limit`, `quota_exhausted`, or `overloaded`. - `provider_error`: `native_provider_model_rejected`, `provider_transport_failed`, `codex_transient_upstream`, `provider_failed`, `provider_tool_definition_invalid`, and the other provider categories. - `waiting_for_person`: `execution_reconciliation_required`, every code in `EXECUTION_RECONCILIATION_CAUSES`, `issue_waiting_for_response`, and `issue_continuation_waiting_on_review`. - `task_changed`: the task was reassigned, paused, closed, blocked, or stopped by a person (`operator_interrupted`, `cancelled`, `interrupted`, `issue_*` lifecycle codes, `agent_paused`, `queued_comment_discarded`). - `platform_error`: process, server, workspace, sandbox, runner, and storage codes (`process_lost`, `server_shutdown_interrupted`, `setup_failed`, `workspace_*`, `environment_provider_unavailable`, `controller_lease_lost`, and others). - `agent_error`: `adapter_failed` without a provider failure, `invalid_output`, `invalid_response`, `tool_error`, `acpx_turn_failed`, `test_run_failed`, `prompt_injection_blocked`, `tool_execution_outcome_unknown`, `timeout`. - `unknown`: any other code, or no code. - On Cloud direct delivery, every new emit site names the responsible person with `withTelemetryActor()` and `resolveTelemetryPerson()`, as `agent.task_run` does: the task creator, else the task's responsible user, else the run owner. `task.created` uses the creating user, else the agent's on-behalf user. `model.connected` uses the user who owns the connection. A live request still wins. The self-hosted collector envelope does not change. - `failure_cause` builds on the run failure code sets in `continuation-cause.ts`. A test fails when a code in those sets has no telemetry code. The provider failure category decides only for `adapter_failed`, `provider_failed`, or no code. - Work product providers outside `paperclip`, `github`, `vercel`, and `s3` are sent as `custom`. - The dispatch workspace check and execution recovery write `blocked` directly. They call the same after-commit helper, with the task's real blockers and unblock owner. The blocker read runs in a savepoint in the issue dependency layer, so a failed read never aborts the block write. - Update the telemetry README with the emit rules, the after-commit rule, and the `failure_cause` source. - Refresh `tests/runner-e2e/source-sdk-public-inputs.json`, because its check reported a change. ## Privacy Review Privacy review requested. Every new dimension is a fixed enum, a boolean, or a count. No dimension carries a title, a body, a plan step, a connection or account name, an email, a URL, a repository name, a prompt, an error message, or an endpoint address. `failure_cause` is a code that the server picks. The run's error text is never sent. The tests check that a provider message and a connection name do not reach the event. ## Verification - `pnpm vitest run packages/shared/src/telemetry/`: 7 files pass, including the new `product-events.test.ts` (helper payloads, omitted optional values, collector envelope with only registered dimensions, retention class). - `packages/db/src/after-transaction-commit.test.ts`: 4 pass (after commit, rollback drop, savepoint, outside a transaction). - `server/src/__tests__/product-telemetry.test.ts`: 14 pass. They check that each event fires once with the right kind and company scope, that a rollback sends nothing, that a repeated status sends nothing, that a later plan revision sends nothing, and that a reconnect sends nothing. - `server/src/__tests__/agent-task-run-telemetry.test.ts`: 35 pass, including the `failure_cause` mapping table and the emit path. - `server/src/__tests__/issue-thread-interactions-service.test.ts -t Plan`: `plan.approved` fires for a plan confirmation and not for an unrelated confirmation. - `server/src/__tests__/posthog-direct-telemetry.test.ts`: the Cloud direct path sends `company_id`, `user_id`, and `attributed_via` for background lifecycle events, an event with no person stays on the workspace, and `failure_cause` passes through. A self-hosted test checks that a person scope leaves the collector events unchanged. - Existing telemetry tests (connector, interaction, run finalizer, heartbeat, AI connection): 299 pass. - `pnpm --filter @paperclipai/shared typecheck`, `pnpm --filter @paperclipai/db typecheck`, and `pnpm --filter @paperclipai/server typecheck`: pass. - `pnpm verify` returned exit 2 (global CI input changed). Required CI supplies the broad coverage. ## Risks - Merge order: merge and deploy paperclipai/telemetry-backend#150 first. If this change ships first, the collector quarantines the new events. The product behavior does not change. - `afterTransactionCommit` uses the existing open-transaction marker in the database client. A callback that a savepoint registers runs when the outer transaction commits, even if that savepoint rolled back. - `task.blocked` adds one small indexed read inside the update transaction, only when a task enters `blocked`. - `failure_cause` adds one small read for a failed run when the caller did not pass the error code. It runs off the run's critical path, as before. - Low risk otherwise. No schema migration. No change to existing event dimensions. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code, with tool use (shell, Git, tests). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
7a0ac92fdf |
fix(runner): tell ACPX agents which field a refused semantic call failed (#22037)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents call Paperclip semantic tools (for example `request_human_input`) through the runner, and the ACPX runner sends each refusal back to the agent > - Today the ACPX runner replaces every refusal with the fixed text "Paperclip semantic operation failed" > - The real reason (for example `summary: too big, max 1000`) is only in the run events, so the agent cannot see it > - Agents then retry the same bad input. One agent retried a questions card 5 times with the same too-long prompt > - This pull request adds the stable error code and, for a validation refusal, each failing field path with its rule and limit to the message > - The value the agent sent, free-text messages and server errors (5xx) stay hidden, as before > - The benefit is that agents can fix a refused call on the next try instead of retrying blind ## Linked Issues or Issue Description Refs #20134 (fixes one case of this problem: the advertised `request_human_input` bounds) **What happened?** An agent called a semantic tool with input that failed server validation. The tool result said only "Paperclip semantic operation failed". The agent retried the same input 5 times, and each retry failed the same way. The run events showed the real cause: `summary: too big, max 1000`. **What did you expect to happen?** The tool result should say which field failed and which rule it broke, so the agent can correct the input. It should not echo the input value or internal diagnostics. **Steps to reproduce** 1. Run an agent on an ACPX provider. 2. Call `request_human_input` with a `prompt` of 1,100 characters (before #20134), or any semantic tool with input that fails zod validation. 3. See the generic "Paperclip semantic operation failed" in the tool result. ## What Changed - New `acpx_tool_failure_feedback` module in `runner-core`. It reads a failed tool result and builds a bounded message from: - a stable error code (lowercase words joined by `_`, `.` or `-`, for example `paperclip_runner_agent_not_found`); - zod-style issues: field path, rule name, type and numeric limit, for example `payload.prompt: too_big, string max 1000`. - It reads the result as an object, an issue list, or a `{success:false, contentItems:[{inputText}]}` envelope whose text is JSON or starts with `code:`. - It never copies `message`, `input`, free text or the input value. Path keys and rule names that do not look like names become `*` or `invalid`. It shows at most 5 issues and 8 path segments. - Any result with a status of 500 or more, or with no recognizable code or issue, keeps the generic message. - `AcpxProviderSession` uses this message for non-terminal semantic failures. Reserved terminal tools keep their current feedback. - Fake ACPX sidecar mode `resolutions-error-detail` and an integration test that checks the message crosses the sidecar boundary without the value. ## Verification - `cargo test -p runner-core --lib acpx_tool_failure_feedback` (7 unit tests: issue lists, envelopes, codes, server errors, free text, masking, bounds). - `cargo test -p runner-core --test acpx_provider_resolutions` (new `tells_the_agent_which_field_failed_validation_without_its_value`, and the existing redaction test still gets the generic message). - `cargo fmt --check`. ## Risks - Low to medium. The main risk is data in error text. The module copies only values that match strict name and number patterns, and never a `message` or `input` field. Tests check that sample values do not appear in the output. - Agents see a longer error message for validation refusals. The message still starts with "Paperclip semantic operation failed", so text matches on that prefix keep working. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in an agent harness. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
92dbf39e6f |
feat(analytics): attribute agent work and onboarding steps to a person on Cloud (#22260)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud sends product events straight to PostHog: server
events from `server/src/services/posthog-direct/` and browser events
from `ui/src/lib/analytics/`
> - A person-level funnel goes from sign-up to the first finished task
> - Agent-driven events (`agent.task_run`, `agent.task_completed`,
`agent.first_heartbeat`) used `workspace:<stackId>` as the distinct id,
so the funnel broke at those steps
> - The in-workspace onboarding wizard sent no step events, so we could
not see where people stop before their first agent
> - This pull request attributes agent work to the responsible person on
the Cloud direct path, and adds consent-gated onboarding step events in
the browser
> - The benefit is one PostHog person per customer across sign-up,
onboarding, agent runs, and task completion. Self-hosted output does not
change.
## Linked Issues or Issue Description
**Subsystem affected**
Cloud product analytics: Cloud direct PostHog delivery (server) and
browser product analytics (UI onboarding wizard).
**Problem or motivation**
A PostHog funnel from sign-up to the first finished task cannot follow
one person. Agent-driven events run in the background, with no signed-in
request, so they use the workspace id as the distinct id. The onboarding
wizard also sends no events, so we cannot see which step people leave.
**Proposed solution**
Give background emit sites a narrow scope that names the person
responsible for the work. Use the task creator first, then the task's
responsible user, then the run owner. Keep the signed-in request user
first. Add `attributed_via` to every Cloud direct event. Add four
browser events to the onboarding wizard. Send them through the existing
analytics module, so the consent rules stay the same.
**Alternatives considered**
A lookup in the transport at send time. We did not use it: it adds
database reads to the telemetry path and loses the emit site's context.
A new contract event for onboarding steps. We did not use it: the server
does not see the wizard steps, and the UI must never send
`PAPERCLIP_EVENTS` names.
**Additional context**
Self-hosted installs keep the collector path. The collector envelope
stays byte-identical (a test checks it).
## What Changed
- `server/src/telemetry-company-scope.ts`: add `withTelemetryActor({
companyId, person }, fn)`, `scopedTelemetryPerson()`, and
`resolveTelemetryPerson()`. The resolver picks the task creator, then
the task's responsible user, then the run owner. It ignores
`local-board`. `withTelemetryCompany` now calls `withTelemetryActor`.
- `server/src/services/posthog-direct/request-context.ts`: a signed-in
request user wins (`attributed_via: request`). Without one, the scoped
person is used.
- `server/src/services/posthog-direct/event-shape.ts`: every Cloud
direct event (including `cloud.workspace_started`) has `attributed_via`
(`request`, `task_creator`, `task_assigner`, `run_owner`, or `none`). An
event with a person keeps today's person-event shape (no
`$process_person_profile: false`).
- `server/src/services/agent-task-run-telemetry.ts`: `agent.task_run`
reads the task creator and responsible user in the existing agent query
(one left join, no new query), and the run's `responsibleUserId`.
- `server/src/routes/issues.ts`: `agent.task_completed` uses the issue
row that the route already has, and the agent actor's `onBehalfOfUserId`
as the run owner.
- `server/src/services/heartbeat/agent-status.ts`:
`agent.first_heartbeat` uses the agent's `createdByUserId` (already
loaded) as the run owner.
- `ui/src/lib/analytics/product-analytics.ts`: add
`captureProductAnalyticsEvent()`. It captures only with a browser
analytics config and granted consent. Events from before posthog-js
loads wait in a queue (at most 50) and keep their time. Withdrawn
consent or a change of signed-in person drops the queue.
- `ui/src/lib/analytics/onboarding-analytics.ts` and
`ui/src/components/OnboardingWizard.tsx`: capture `onboarding_opened`,
`onboarding_step_viewed`, `onboarding_step_completed` (with `step` and,
for `connect_model` and `launch`, `outcome`), and
`onboarding_dismissed`. `step` is `create_agent`, `connect_model`,
`review`, or `launch`. No event has free text.
- Docs: `packages/shared/src/telemetry/README.md` (Cloud Direct
Delivery) and `doc/cloud-browser-analytics.md` (new "Onboarding events"
section).
## Verification
- `server/src/__tests__/posthog-direct-telemetry.test.ts`: attribution
matrix (creator, assigner, run owner, none stays on
`workspace:<stackId>` with `$process_person_profile: false`), the
request user wins over the scope, and the self-hosted collector envelope
is byte-identical with a person scope.
- `server/src/__tests__/agent-task-run-telemetry.test.ts` (embedded
Postgres): `agent.task_run` scope for creator, assigner, run owner, and
nobody; another company's task is never read.
- `server/src/__tests__/issue-telemetry-routes.test.ts`:
`agent.task_completed` scope for creator and assigner.
- `server/src/__tests__/heartbeat-process-recovery.test.ts`:
`agent.first_heartbeat` scope is the agent owner.
- `ui/src/components/OnboardingWizard.test.tsx`: a launch for the old
company that settles after a switch to another company does not end the
new analytics session.
- `ui/src/lib/analytics/onboarding-analytics.test.tsx`: each transition
fires once, held events drop on a person change, a stale opening step is
not a view, dismissal fires once, nothing is captured when analytics is
off or consent is `denied` or `ask`, and queued events keep their time.
- `ui/src/lib/analytics/product-analytics-events.test.ts` still passes
(the UI never captures a `PAPERCLIP_EVENTS` name).
- Local Cloud-mode run: an isolated instance (own Postgres, trusted
Cloud tenant headers, `PAPERCLIP_POSTHOG_HOST` set to a local capture
server, never real PostHog). A stub stood in for posthog-js and sent
through the `/_ph` proxy.
- A user created a task and assigned it to the agent. `agent.task_run`
arrived with `distinct_id: paperclip-id:local-user-1`, `attributed_via:
task_creator`, the raw `task_id`, and no `$process_person_profile`. (The
run itself failed locally because the Cloud runner is not available. The
event still shows the attribution.)
- `agent.first_heartbeat` arrived with the same person and
`attributed_via: run_owner`. `server.started` kept
`workspace:stack-local` with `attributed_via: none`.
- Headless Chromium walked the wizard: `onboarding_opened`
(create_agent), `onboarding_step_viewed` (create_agent),
`onboarding_step_completed` (create_agent), `onboarding_step_viewed`
(connect_model), `onboarding_step_completed` (connect_model, `api_key`),
`onboarding_step_viewed` (review), `onboarding_step_completed` (review),
`onboarding_step_completed` (launch, `succeeded`). Each fired once, with
the signed-in user as the distinct id. Events from before posthog-js
loaded arrived with their original time.
- A second walk left the onboarding page on the connect step and sent
one `onboarding_dismissed` (connect_model).
## Risks
- Low risk for self-hosted: the collector path never reads the new
scope, and a test checks the envelope bytes.
- Cloud: agent events move from the workspace person to a real person.
Insights that count `workspace:` distinct ids for these events will
change. `attributed_via` lets a query filter or split them.
- `task_assigner` uses the task's responsible user. Paperclip does not
store who assigned a task, so this is the person who owns or delegated
the task.
- Privacy: the new data is Cloud-only and uses ids that Cloud events
already carry. No new free text, email, or name goes on an event.
**Privacy review requested** for the Cloud attribution change (per
`rules/data-paths.mdc`). The generated contract does not change:
`attributed_via` is a Cloud-only property, like `stack_id` and
`user_id`.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, headless browser).
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
6b980871b5 |
fix(grok-local): copy SSH skill contents into the created directory (#22120)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The `grok_local` adapter can run a Grok agent on a remote SSH workspace > - Before the run, `prepareGrokRemoteProjectAssets` copies the selected skills into `.claude/skills` on the target > - It creates each skill directory and then calls `fs.cpSync` on that same directory with `force: false` and `errorOnExist: true` > - Node 24 rejects this with `ERR_FS_CP_EEXIST`, so every Grok run over SSH fails with "Could not prepare Grok SSH runtime assets" > - This pull request copies the contents of each skill into the new empty directory > - The benefit is that Grok SSH runs work again and the shared CI test groups go green on master and on open PRs ## Linked Issues or Issue Description Refs #22078 **What happened?** Every Grok run on an SSH target fails before it starts. The error is "Could not prepare Grok SSH runtime assets". The script on the target fails with `SystemError [ERR_FS_CP_EEXIST]: Target already exists: cp returned EEXIST (.../.claude/skills/selected already exists)`. **Steps to reproduce** 1. Use Node 24. 2. Run `pnpm --filter @paperclipai/adapter-grok-local exec vitest run src/server/remote-project-assets.test.ts`. 3. The "existing", "new" and "changed" cases fail. **Expected behavior** The skills are copied into `.claude/skills/<name>`, and the existing project files stay safe. **Impact** CI fails on master and on unrelated open PRs: - `ci / General tests (workspaces-b)`, in `remote-project-assets.test.ts` - the server group that runs `ssh-remote-workspace.integration.test.ts > runs an assigned grok_local-cli task through heartbeat over SSH` ## What Changed - `packages/adapters/grok-local/src/server/remote-project-assets.ts`: after the script creates a skill directory, it now copies each child of the source skill into that directory. Before, it copied the skill directory onto itself. The copy keeps `force: false` and `errorOnExist: true`, so it still does not overwrite files. ## Verification - Red: on `origin/master` with Node v24.22.3, `remote-project-assets.test.ts` fails 3 of 4 cases with `ERR_FS_CP_EEXIST`. I saw this error in the script's stderr. - Green: with this change, `vitest run src/server` in `packages/adapters/grok-local` passes 137 tests in 9 files, and all 4 cases of `remote-project-assets.test.ts` pass. - I could not run the SSH integration test locally. It needs a real SSH server, so it is skipped here. CI runs it. ## Risks Low risk. The change affects only the copy step for each new skill directory. Cleanup and the safety checks for symlinks and paths do not change. The script creates the target directory just before the copy, so the directory is empty. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge The existing `remote-project-assets.test.ts` cases already cover this bug: they fail before the fix and pass after it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
c600d69242 |
Let plugin connectors declare their tool timeout (#22249)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Plugins can serve connector tools from their worker (`transport: "plugin"`, added in #22004, #22019 and #22201). > - The tool gateway runs these tools with a fixed 10 s default timeout. > - Some plugin tools call backends that take 12–20 s. These calls fail every time with "Tool execution timed out", even though the plugin's own HTTP client waits much longer. > - The plugin connector design said that the connector, not a fixed gateway constant, sets the timeout. > - This pull request lets a plugin method or a single static tool declare `timeoutMs`, and gives plugin-served tools a 30 s default. > - The benefit is that a plugin connector can serve slow tools like other connectors can, within the same 60 s gateway ceiling. ## Linked Issues or Issue Description Refs #22004, #22019, #22201. Refs #20746. **Relationship to #20746.** This PR builds alongside #20746. It does not supersede it. #20746 changes the default for legacy top-level plugin tools (provider `paperclip_plugin`) to 60 s. This PR changes only plugin-served connector tools (provider `paperclip_plugin_connection`, `transport: "plugin"`). The two PRs touch different branches of the gateway and can merge in either order. This PR does not pin the legacy default in its tests, so #20746 does not break them. **Current behavior** A plugin connector tool always times out after 10 s, unless the caller sends `timeoutMs`. Agents and runners do not send it. The worker RPC also stops at 30 s. **Proposed behavior** A plugin can declare `timeoutMs` (1000–60000 ms) on a `transport: "plugin"` method or on one static tool. The gateway uses that value. If nothing is declared, the gateway waits 30 s. **Reason and benefit** Plugin tools whose backends take longer than 10 s can now work. Plugin authors control the value in the manifest, and the gateway keeps its 60 s ceiling. **Breaking changes** None. Existing manifests stay valid. Only plugin-served tools get the new 30 s default. ## What Changed - `packages/shared`: `timeoutMs` is a new optional field on `ConnectionMethodDef` and on `PluginConnectorToolDef`. The validator accepts integers from 1000 to 60000 only. It rejects `timeoutMs` on methods that do not use `transport: "plugin"`. New exported constants: `PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS`, `PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS`, and `PLUGIN_CONNECTOR_TOOL_DEFAULT_TIMEOUT_MS` (30000). - `server/src/services/plugin-connector-runtime.ts`: `pluginConnectionToolTimeoutMs()` resolves the timeout in this order: the tool's value, then the method's value, then 30 s. The worker `executeTool` RPC now gets the gateway timeout plus 1 s. Thus the gateway's `tool_timeout` error is what callers see, and the 30 s RPC default no longer cuts off a longer declared timeout. - `server/src/services/tool-gateway.ts`: `executePluginConnectionTool` now applies the timeout itself, after it loads the connection. All three plugin paths use it: session, assigned-tool and direct calls (`executeTool`), test calls (`executeTestCall`), and approved action execution. If a caller sends `timeoutMs`, that value wins, as before. It is still clamped to 60 s. Approved actions keep their fixed 60 s budget. - Other transports do not change. Remote MCP, local stdio, built-in and legacy plugin tools keep their timeouts. (#20746 separately proposes a 60 s default for legacy plugin tools.) - Docs: `doc/plugins/PLUGIN_SPEC.md` §11A and the plugin SDK README describe the field, its range, and the default. The SDK manifest type gets the field from `@paperclipai/shared`. ### Why 30 s 30 s is the same as the plugin worker manager's default RPC timeout. So, before this change, the worker already allowed 30 s, and only the gateway's 10 s limit stopped the call. With 30 s, the common 12–20 s backend case works without a declaration. It is also well under the 60 s ceiling. Tools that need more time can declare up to 60 s. ## Verification - New `server/src/__tests__/plugin-connector-tool-timeout.test.ts` runs the real gateway invocation path against an embedded Postgres and a fake worker. Fake timers make the 12 s backend free in wall-clock time: - With method `timeoutMs: 30000`, a 12 s tool succeeds through `executeTool` and through `executeTestCall`. The worker RPC timeout is 31000. - With tool `timeoutMs: 5000`, a 12 s tool fails at 5 s with `504 tool_timeout`. - With no declaration, a 12 s tool succeeds (it failed at the old 10 s), and a 45 s tool times out at 30 s. - Manifest values above 60000, below 1000, or not integers are rejected. A caller `timeoutMs: 120000` is clamped to 60 s. - A legacy plugin tool (`paperclip_plugin`, a different provider path) never reaches the connector runtime, and a caller deadline still applies. This test does not pin the legacy default, because #20746 changes it. - Remote MCP, local stdio and REST timeouts do not change in this PR. Their existing timeout tests in `tool-gateway.test.ts` and `google-workspace-rest-transport.test.ts` still apply. - Red/green: with the source change reverted, 4 of these 5 tests fail. The legacy-tool test passes both ways, as expected. - `packages/shared/src/plugin-apps.test.ts`: validation cases for the range, non-integer values, and non-plugin methods. - Commands run: - `pnpm --filter @paperclipai/shared typecheck && pnpm --filter @paperclipai/server typecheck && pnpm --filter @paperclipai/plugin-sdk typecheck` - `cd server && npx vitest run src/__tests__/plugin-connector-tool-timeout.test.ts src/__tests__/plugin-connectors-plugin-transport.test.ts src/__tests__/plugin-connector-agent-grant.test.ts` (20 passed) - `cd packages/shared && npx vitest run src/plugin-apps.test.ts src/app-definitions.test.ts` (76 passed) - `pnpm check:module-boundaries` - Full suite not run locally. CI supplies it. ## Risks - Low risk. Plugin-served tools now wait up to 30 s instead of 10 s by default. An agent turn can wait longer for a slow or stuck plugin tool, but never longer than the existing 60 s ceiling. - The connection row lookup now runs before the timeout timer starts. This is one indexed query. - Dynamic tool lists (`kind: "dynamic"`) use the method's `timeoutMs`. Per-tool values apply to static tools only. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use (shell, file edits, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
4434714824 |
Fix sidebar Recents task order and archive visibility (#22251)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The sidebar gives people quick access to tasks, chats, and projects they recently opened. > - Expanding a parent or project in Recents can show tasks the person never opened. > - Archiving a task from the inbox leaves it in Recents. > - This change gives each recent task its own row and removes tasks archived for the current viewer. > - People can reopen an individual task and keep saved shortcuts above More. ## Linked Issues or Issue Description **What existing behavior does this improve?** Recents in the Standard and Classic sidebars. **Subsystem affected** Board navigation and task summaries. **Current behavior** Opening a parent or project can show other tasks beneath it. A recent subtask moves its parent group when reopened. Archiving a task leaves its recent link visible. **Proposed behavior** Show each visited task in its own row, in recent activity order. Keep canceled and completed tasks eligible. Remove tasks archived for the current viewer from Recents. Preserve saved pins. **Reason and benefit** People can find the task they opened by its own position in the list. Archiving removes its recent link without removing a saved shortcut. **Breaking changes** The Recents rows no longer expand into task lists. Project links still open the project. The navigation summary adds an optional personal archive flag. Related work: #22219, #22024, #21904, and #20450. ## What Changed - Render task, agent chat, and project rows directly in Standard Recents. Keep the existing controls to pin each kind of row. - Render standalone task rows with the existing Classic action menus. Remove sidebar child loading and refresh code. - Derive the viewer’s archive state using the existing inbox rule. Filter archived tasks out of Recents while retaining authorized pinned shortcuts. - Cover independent parent and child order, canceled and archived tasks, pin retention, and the Classic Archive action. ## Verification - Reproduced the empty Recents row after cancellation before the fix. - On the rebased branch, 424 focused UI and live-update tests and the UI typecheck passed on macOS. - Ran 77 issue-summary and OpenAPI integration tests with embedded PostgreSQL on macOS. The Runner source SDK registry check passed on the pushed revision. - The updated sidebar test renders 402 recent rows. A deliberate repeated task lookup made the input-read guard fail. The restored implementation passed. - The paused-assignee browser test checks the task detail heading in each interface. Both variants reproduced the CI locator failure locally and passed with the scoped locator. - All 17 focused Storybook browser checks passed in Chromium on macOS. - Run `pnpm verify` for local selection. The product documentation change requests broader GitHub CI coverage. - Open a parent task and a child task in either sidebar. Reopen the child and check that its row moves ahead of the parent. Cancel the child and check that it stays visible. Archive it and check that its recent row disappears. - On commit `8051038099`, [GitHub CI](https://github.com/paperclipai/paperclip/actions/runs/44421716811) passed, including the required verification and end-to-end checks. - [Greptile](https://github.com/paperclipai/paperclip/pull/22251#issuecomment-6994494812) rated the same commit 5/5. Its review thread is resolved. ## Risks - Recents uses the same viewer-specific archive rule as the inbox. Archiving prunes the local recent entry. A restored task can enter Recents again when opened. - Task summaries still return authorized tasks for saved pins. Child and unread counts remain in the existing API response for older clients. - The change requires no database migration. ## Model Used - OpenAI GPT-6 via Codex with shell, GitHub CLI, Vitest, and Chromium. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Scott Tong <1504818+scotttong@users.noreply.github.com> Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
45c3f4caa2 |
fix(connectors): require an install before an agent reaches a plugin connector (#22237)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Plugins can add connectors that serve their own tools (`transport: "plugin"`, #22004, #22019, #22201) > - The activation rule is that an agent gets a connector's tools only through an install of an active connection for that agent > - An agent with no install could still list and call a plugin connector's tools, and the plugin worker ran them with that agent's run context > - This pull request makes the tool access policy require the install for plugin-served connections > - The benefit is that a plugin connector reaches only the agents it is installed for ## Linked Issues or Issue Description Refs #22004 Refs #22019 Refs #22201 **Subsystem affected** Tool access policy and tool gateway (plugin-served connectors). **Problem or motivation** A plugin connection was installed for agent A only. Agent B, a standard agent with no install, called one of its tools. The plugin worker got a run context with B's agent id. **Root cause** An install gives access only through the connection's app profile binding. The policy does not check installs. For an agent outside that profile, the policy goes on to its other allow routes. The common route is the unscoped `tools:use` grant that every new standard agent receives (`NEW_STANDARD_AGENT_DEFAULT_GRANT_KEYS`). `governedByConnectionProfile` is false for B, because B is not bound to the connection's profile. So `explicitGrant` allowed the tool for discovery and invocation. Organization-grant connections ran the worker. Per-agent connections listed the tools and reached grant resolution. **Expected behavior** An agent without an install for the connection (or a company install) sees no tools and cannot call them. An installed agent is not affected. ## What Changed - `server/src/services/tool-access-policy.ts`: for an agent caller on a connection whose stored transport is `plugin`, deny with the new reason `deny_connection_not_installed` unless an install exists for that agent or the company. The check runs before profiles, grants, trust rules and allow policies, so none of them can replace the install. It reads the transport from the stored connection, not from the caller. The install read uses the decision cache, so a listing batch reads it once per connection. - `packages/shared/src/types/tool-access.ts`: add `deny_connection_not_installed` to `ToolAccessReasonCode`. - `doc/connections/CONNECTOR-PLAYBOOK.md`: document the rule. - Legacy plugin tools (`paperclip_plugin`) keep their own implicit-install gate and are not changed. ## Verification - New `server/src/__tests__/plugin-connector-install-gate.test.ts` (embedded Postgres, real routes). Both agents get the default standard-agent grants, including the unscoped `tools:use`. For an organization-grant connection and a per-agent connection installed for A only: - A lists the tool through its gateway session and its Paperclip Runner assigned-tool gateway, and a call reaches the worker. - B (with its own install of an unrelated connection) lists none of them in either path. - B's direct call by name through its gateway session, its runner gateway, and the runner's `paperclip_call_assigned_tool` is refused. The worker is never called. - Before the fix, both cases failed: B listed the tool. - Regression suites pass: `tool-access-policy-service`, `tool-access-policy-index`, `tool-gateway`, `tool-gateway-service`, `tool-gateway-*`, `prompt-injection-gateway`, `plugin-connectors-plugin-transport` (legacy plugin tools), `plugin-connectors-circleback-parity`, `plugin-connector-agent-grant`, `heartbeat-runtime-mcp-servers`, `run-preparation`, `tool-access-service`, `generic-mcp-connection`, `remote-mcp-connectors`, `railway-connection`, `aws-mcp-connector`, `mcp-protocol-versions`, `google-workspace-*`. - `tsc --noEmit` passes for `server`, `packages/shared` and `ui` source. ## Risks - Behavior change: an uninstalled agent loses access to plugin-served connection tools it reached before through a general grant, a trust rule or an allow policy. That access broke the activation rule. Installed agents and company installs are not affected. - The board's per-agent access check now shows `deny_connection_not_installed` for agents without an install. - Built-in (non-plugin) connections are not changed by this pull request. They have the same policy path. Whether to require installs for them is a separate decision, because existing setups may depend on it. - No migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
07d9316218 |
fix: restore master's typecheck and runner SDK input pin (#22242)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - #22235 added a runner regression test for a turn lost to a mid-run `runnerd` restore > - That test reads `startTurn.mock` inside the initializer of `startTurn` itself > - The CI test-program typecheck rejects this with TS7022 and TS7024, so master fails "Typecheck + Release Registry" > - This pull request counts calls in a local variable instead > - The benefit is that master typechecks again, and the test behaves exactly as before ## Linked Issues or Issue Description Refs #22235, Refs #22234 **What happened?** After #22235 merged, `ci / Typecheck + Release Registry` failed on `packages/paperclip-runner/src/native-session-runtime.test.ts(724)` with TS7022 ("'startTurn' implicitly has type 'any'...") and TS7024. **Steps to reproduce** 1. Run the CI typecheck lane (`typecheck test programs`) on master after #22235. 2. See TS7022 and TS7024 at line 724 of the test. **Expected behavior** The test program typechecks. ## What Changed - The `startTurn` mock in the new test uses a local call counter instead of reading its own `mock.calls`. - `tests/runner-e2e/source-sdk-public-inputs.json`: refresh the pin for `packages/shared/src/app-definitions/github.json`, which #22234 changed without updating it. The Runner support suite fails on master without this. ## Verification - `npx tsc -p packages/paperclip-runner/tsconfig.test.json --noEmit` reports no errors in the test file. - `npx vitest run src/native-session-runtime.test.ts` in `packages/paperclip-runner`: 301/301 pass. ## Risks - Low risk. This changes a test and regenerates a pin with the repository script (`node tests/runner-e2e/source-sdk-public-inputs.mjs <sha> --write`). `source-sdk-public-inputs.test.mjs`: 13/13 pass. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
eaac8ed0f7 |
feat(adapters): add Claude Fable 5.2 and GPT-6.2 with CLI floors, and refresh sandbox CLI pins (Nov 18 audit) (#22222)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents run on coding harnesses. Each adapter has a model catalog, and sandboxes contain pinned CLIs. > - Anthropic released Claude Fable 5.2 and OpenAI released GPT-6.2 Sol and GPT-6.2 Astra for Codex. Both need newer CLIs than the Paperclip Runner provider pack ships. > - A stale catalog hides valid models. A model that needs a newer CLI fails with an opaque backend error. > - This pull request adds the verified model IDs with their CLI floors, names the version gap in Paperclip Runner, and refreshes the sandbox CLI pins. > - The benefit is that operators can select current models and get a named version error instead of a backend failure. ## Linked Issues or Issue Description Refs #20774 and #21636 (both add parts of Fable 5.2 support; see "Overlap" below). Refs #18486 (adds GPT-6.1 Terra; this PR does not duplicate it). Refs #16708 (adds Claude Haiku 5.5 to `claude_local`; this PR does not duplicate it). **What happened?** Claude Fable 5.2 (`claude-fable-5-2`) and GPT-6.2 Sol / Astra (`gpt-6.2-sol`, `gpt-6.2-astra`) are generally available. The `claude_local`, `codex_local`, and OpenCode pickers do not list them. Claude Code 2.1.321 is the first release with Fable 5.2. Codex 0.169.1 is the first release whose bundled catalog lists GPT-6.2. The Paperclip Runner provider pack bundles Claude Code 2.1.286 and Codex 0.160.0. **Expected behavior** The pickers list the new models. A run on a CLI below the model minimum stops with the detected and required versions, or falls back to a compatible model with a visible message. **Proposed change** Add the models and their per-model CLI floors. Gate ACPX Claude in Paperclip Runner on the Claude Code version that its Agent SDK bundles. Refresh the sandbox CLI pins with verified digests. Record the audit. ## What Changed - Claude Code (`claude_local`): - Add `claude-fable-5-2` (label "Claude Fable 5.2") at the top of the picker. `claude-fable-5-1` stays selectable after the current-generation models. - Add Bedrock `global.anthropic.claude-fable-5-2`. Anthropic documents only this global ID for Bedrock. - Fable 5.2 offers all five efforts (`low` to `max`). - `minimumClaudeCliVersionForModel("claude-fable-5-2")` returns `2.1.321`. The existing CLI-lane Test and launch checks use this floor. On a managed sandbox, the CLI lane installs a private Claude Code at this version, as it does for the other floors. - Paperclip Runner (ACPX Codex): `resolvePaperclipRunnerProviderProfile` rejects a model whose Codex floor is above the qualified ACPX Codex runtime (`0.160.0`). The error code is `paperclip_runner_codex_cli_version_incompatible`, and the message gives both versions. - Paperclip Runner (ACPX Claude): `resolvePaperclipRunnerProviderProfile` rejects a model whose Claude Code floor is above the version that the qualified Agent SDK bundles. The error code is `paperclip_runner_claude_cli_version_incompatible`. The message gives both versions. A new helper, `claudeCodeVersionForAgentSdk`, maps SDK `0.3.N` to Claude Code `2.1.N` (the SDK's `claudeCodeVersion` field) and returns `null` for any other line. - Codex (`codex_local`): - Add `gpt-6.2-sol` and `gpt-6.2-astra` at the top of the picker, in the bundled catalog order. - Both offer Fast mode and the `low` to `ultra` efforts. - Both have a CLI floor of `0.169.1`. On the native Codex provider with the pinned Codex 0.160.0, the existing fallback moves `gpt-6.2-sol` to `gpt-6.1-sol` and `gpt-6.2-astra` to `gpt-6-astra` with a visible message. - The default stays `gpt-6.1-sol`. - OpenCode fallback catalog: add `openai/gpt-6.2-sol`, `openai/gpt-6.2-astra`, `anthropic/claude-fable-5-2`, `google/gemini-4-carbon`, and `google/gemini-4-hydrogen`. - Evaluation image sandbox layer (`docker/daytona-runner`): | CLI | Before | After | | --- | --- | --- | | Grok CLI | 1.0.70 | 1.0.89 | | Gemini CLI | 0.65.0 | 0.68.0 | | Cursor CLI | 2026.10.22-27dcf5f | 2026.11.17-f532c45 | | GitHub CLI | 2.103.3 | 2.105.0 | - Add `doc/adapter-model-audit-2026-11-18.md` with sources, compatibility findings, and deferred items. Add a note on above-window Codex floors to `doc/architecture/paperclip-runner-compatibility.md`. No saved agent changes model, effort, or spending settings. No picker entry is removed. ### Managed sandboxes On Paperclip Runner, Fable 5.2 and GPT-6.2 stay unusable until the provider pack moves to Claude Code 2.1.321 or later and Codex 0.169.1 or later. A sandbox image that carries that provider pack must also be promoted. This PR does not change the provider pack (see "Deferred items" in the audit). Native remote Codex accepts only `>=0.149.0 <0.161.0`, so GPT-6.2 also needs that window to move. ### Overlap - #21636 sets the Fable 5.2 floor to `2.1.290`. The [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) adds Fable 5.2 in 2.1.321. `git merge-tree` merges the two without a text conflict, but #21636's line becomes unreachable after this PR's line, and its test then fails. Rule: keep `2.1.321`. Merge this PR first. Then close #21636 or change its floor and test to `2.1.321`. - #20774 (draft) lists `claude-fable-5-2`. It conflicts in `packages/adapters/claude-local/src/index.ts` and `server/src/__tests__/adapter-models.test.ts`. Rule: keep this PR's catalog order and Bedrock ID. - #18486 adds `gpt-6.1-terra`. It conflicts in `packages/adapters/codex-local/src/index.test.ts` and `src/server/codex-args.test.ts` (the ordered ID list and the Fast-mode message). Rule: keep both sets of models in the bundled catalog order (`gpt-6.2-sol`, `gpt-6.2-astra`, `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6.1-terra`, ...). Either PR can merge first; the second rebases. - #16708 adds Claude Haiku 5.5. It conflicts in `packages/adapters/claude-local/src/index.test.ts` (adjacent test cases) and `doc/DEVELOPING.md`. Rule: keep both test blocks. ## Verification Research date: November 18, 2026. Sources are listed in the audit doc. - `vitest run src/index.test.ts src/server/model-order.test.ts src/server/cli-capabilities.test.ts src/server/test.remote.test.ts` in `packages/adapters/claude-local`: 40 passed. `execute.remote.test.ts` (29), `test.probe.test.ts` (21), `sandbox-cli-version.test.ts` (15), `acp.auth.test.ts` (25), and `acp.test.ts` (47, with `--testTimeout=60000`) also passed when run one file at a time. - `vitest run src/index.test.ts src/server/codex-args.test.ts src/ui/build-config.test.ts src/server/test.remote.test.ts` in `packages/adapters/codex-local`: all passed (155). `acp.test.ts` (49), `acp.cli-version.test.ts` (4), and `execute.test.ts` (10) also passed one file at a time. - `vitest run` in `packages/adapters/opencode-local`: 94 passed. - `vitest run src/services/native-runtime/acpx-qualification.test.ts src/services/native-runtime/codex-model-fallback.test.ts src/__tests__/adapter-models.test.ts src/__tests__/heartbeat-model-fallback-warning.test.ts` in `server`: all passed. The new cases cover the ACPX Claude and ACPX Codex version errors and the native GPT-6.2 fallback on Codex 0.160.0. - `vitest run src/lib/agent-setup-fields.test.ts src/lib/codex-reasoning-effort.test.ts` in `ui`: 11 passed. - `tsc --noEmit` in the three adapters and `pnpm typecheck` in `server`: passed. - Cursor archive SHA-256 `189ed41d8963cd22dcdafbbd62f072cc55ac08374c922dbd04aee525f4018ab6` is computed from the versioned Linux x64 tarball. The extracted binary reports `2026.11.17-f532c45`, the version that `https://cursor.com/install` resolves. - GitHub CLI SHA-256 `79e7ab5db738c48777b696e374f8b428f0647debfb424f44d2f426370407fe2f` matches `gh_2.105.0_checksums.txt`. - Grok CLI 1.0.89 and Gemini CLI 0.68.0 installed from npm report those versions. The flags that Paperclip uses are in `--help` (`-m`, `--effort`, `grok models`; `-m`, `-p`, `--output-format`, `--approval-mode`, `--yolo`). - Host baseline: tests that create an AI provider need the host's empty `ANTHROPIC_BASE_URL` unset. Under full-package parallel runs, SSH and sandbox fixture tests time out at 5 seconds on this host; each file passes alone. The audit doc records both. - Not run locally: the full `pnpm -r typecheck`, `pnpm build`, browser suites, and the image build. CI runs these. No live model inference ran. ## Risks - Low risk for saved agents: no default, saved model, effort, or spending setting changes. - The new Paperclip Runner checks reject `claude-fable-5-2` on ACPX Claude and `gpt-6.2-*` on ACPX Codex (and any later model whose floor is above the bundled runtime) before launch. Without this PR, the turn would start and fail at the backend. - The `0.3.N` → `2.1.N` mapping covers only the current SDK line. Any other line returns `null`, and the check is skipped. - The sandbox CLI pins change only the evaluation image. The fleet image change is separate. - Rollback: revert this PR. No data migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code with tool use (shell, web fetch, file edits). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
d668eeb660 |
fix(runner): keep Claude MCP bearer tokens out of process arguments (#22206)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for work
> - The runner starts Claude through ACPX and the Claude ACP agent.
> - The runner gives Claude HTTP MCP servers: the task tool bridge and hosted connectors. Each server has a bearer token.
> - The Claude Agent SDK writes these servers, with their headers, into the inline `--mcp-config` argument of the Claude CLI.
> - Thus a `ps aux` or `ps -ef` command in the sandbox shows the bearer tokens. Tool logs then keep the tokens.
> - This pull request sends a `${VAR}` reference in the header. The token goes into the launch environment of the agent.
> - The benefit is that process lists do not show MCP bearer tokens.
## Linked Issues or Issue Description
**What happened?**
An agent ran `ps aux` in its sandbox. The output showed the Claude CLI process with an `--mcp-config` argument. That argument had an `Authorization: Bearer <token>` header for each HTTP MCP server. The tool log kept the full output.
**What did you expect to happen?**
Process arguments must not contain credentials. A process list must not show MCP bearer tokens.
**Steps to reproduce**
1. Start a Claude agent on the runner with the task tool bridge or a hosted connector.
2. In the agent, run `ps -ef`.
3. Look at the Claude CLI line. The `--mcp-config` JSON contains `"Authorization":"Bearer ..."`.
**Root cause**
`openQualifiedAcpxRuntime` sent the literal `Bearer <token>` header in the ACP `mcpServers` list. The Claude ACP agent gives this list to the Claude Agent SDK. The SDK always serializes it into `--mcp-config <json>` on the CLI command line.
## What Changed
- For the Claude ACPX profile, each HTTP MCP header now has the value `Bearer ${PAPERCLIP_ACPX_MCP_BEARER_<n>}`.
- The runner puts each token in the Claude launch environment under the same name. Claude Code expands `${VAR}` in `--mcp-config` when it connects to the server.
- Other ACPX agents keep the literal header. Their CLIs do not have a known `${VAR}` expansion.
- Added a regression test. Updated one exact launch-environment assertion for the new variable.
## Verification
- Failing before the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter.test.ts -t "MCP bearer tokens out of the CLI argv"` (in `packages/paperclip-runner`). It failed with `expected '[{"type":"http","name":"paperclip",…' not to contain 'bridge-secret'`. The projected header had the literal synthetic token.
- Passing after the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter` — 7 files, 136 tests passed.
- Manual check of the expansion: I ran the pinned Claude CLI (agent SDK 0.3.286) with `--mcp-config` and a header `Bearer ${SYNTH_MCP_BEARER}` against a local HTTP server. The server got the expanded synthetic value.
- `tsc --noEmit -p packages/paperclip-runner`: no new errors. The only errors are in `src/eval/workflow-harness.ts` and occur on `master` too, because my local install did not include the eval kernel package.
- The full `src/drivers/acpx/` folder has other failures in this sandbox (`EACCES` on `/proc/self/fd` spawn, directory fsync). The same failures occur on `master` without this change.
## Risks
- Medium-low risk. If a future Claude CLI stops the `${VAR}` expansion in `--mcp-config`, MCP calls fail authentication. They do not leak the token. The regression test pins the header shape.
- The token is now in the Claude process environment. Only the same user can read `/proc/<pid>/environ`. Other credentials are already in this environment. Shell tools that Claude starts also inherit the environment, so `env` output can still show the token. Log redaction must continue to cover bearer values.
- Tokens that already appeared in logs are not revoked by this change.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code execution.
## Checklist
- [x] I have included a thinking path that traces from project context to this change
- [x] I have specified the model used (with version and capability details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before requesting merge
Related: #13572 removes bearer tokens from curl arguments in the agent helper scripts. This pull request covers the Claude CLI MCP configuration.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
bb258a5429 |
fix(connections): explain failed app sign-ins and guide GitHub app install (#22234)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents can ask a person to connect an app, such as GitHub, through a
sign-in window
> - When that sign-in fails, the server knows the reason and records it
in the activity log
> - The sign-in window tells the opener only "failed", so the person
sees "Authorization did not complete" for every cause
> - People cannot fix the problem themselves, and support cannot help
without reading server data
> - This pull request sends the safe failure code to the opener and
shows plain copy for the common causes
> - The benefit is that a person knows what to do next, such as to
finish faster or to stay in the same session
## Linked Issues or Issue Description
**What happened?**
A user tried to connect GitHub from an agent request. The dialog showed
"GitHub couldn't connect. Authorization did not complete. Try again when
you're ready." The same text shows for every failure cause.
**Expected behavior**
The dialog should tell the user why sign-in failed and what to do next.
**Steps to reproduce**
1. Start an app connection from an agent request.
2. Let the sign-in take longer than the state lifetime, or finish it in
a different Paperclip session.
3. See the generic "Authorization did not complete" message.
**Paperclip version or commit**
`master` at
|
||
|
|
06750cb18e |
fix(runner): continue a turn lost to a mid-run runnerd restore (#22235)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents in a managed sandbox run under the Paperclip runner (`runnerd`). When `runnerd` exits mid-run, the transport relaunches it in the same execution, and the runner restores the same conversation > - An agent can fill the sandbox disk with its own work. `runnerd` then cannot write its state and exits. #22068 added a disk reserve so the relaunch succeeds. Its stated goal was that "the agent's turn can continue and see the full disk" > - The relaunch now works, but the turn still dies. The runner reports the in-flight turn as `provider_turn_lost_on_restore`. The runtime sends its single same-conversation continuation only for a session recovered at startup under a control-plane restart claim. A relaunch inside the live execution has neither, so the run fails as `native_provider_terminal_failed` > - The generic transient retry then starts on a fresh sandbox, redoes the same install, fills the disk again, and ends in board-owned "Recovery needed" > - This pull request lets the execution that started a turn send the existing one-time continuation when the runner reports that same turn lost on restore > - The benefit is that the agent keeps its conversation and workspace and sees the full disk in its own tools, instead of the run dying and retrying into the same wall ## Linked Issues or Issue Description Refs #22068 **What happened?** On staging, two agent tasks on the Paperclip monorepo each failed on every attempt (5 failed runs in total). Each run used a fresh managed Daytona sandbox with 10 GiB of disk. The agent's own `df` showed `/` at 10G of 10G with 236K free. `node_modules` used 3.2G and `.paperclip-runtime` used 6.1G: about 3.0G of provider pack and a 2.8G pnpm store under the session data directory. `runnerd` exited with `failed to create private durable state temporary file: No space left on device (os error 28)`. The transport relaunched it in about 20 s, and runnerd restored its durable session. Then the runner reported `turn.failed {code: provider_turn_lost_on_restore, recoverable: true}`, and the run failed as `native_provider_terminal_failed`. Retries on fresh sandboxes hit the same failure. The tasks ended in "Recovery needed" with `provider_failure_meaning_unverified`. **Steps to reproduce** 1. Run an ACPX or Codex agent through `paperclip_runner` in a managed sandbox. 2. Have the agent fill the disk during a turn, or end `runnerd` in any other way mid-turn while the server keeps running. 3. The transport relaunches `runnerd`, and the runner reports the turn as lost on restore. 4. The run fails instead of continuing the turn. **Expected behavior** The execution that started the turn sends one continuation turn in the restored conversation, exactly as it does after a server restart. The agent continues from its recorded progress and sees the full disk in its tools. **Environment** Managed Daytona sandbox (fleet snapshot, 4 CPU, 8 GiB memory, 10 GiB disk), `paperclip_runner` native runtime with Claude through ACPX. ## What Changed - `packages/paperclip-runner/src/native-session-runtime.ts`: the execution records the turn id of the turn it starts. `resumeInterruptedTurn` now accepts two owners of a turn lost on restore: - a session recovered at startup with the control-plane restart claim, for the checkpointed active turn (unchanged), or - a session this execution opened itself, for the turn this execution started (new). - All other guards stay: one continuation per run, the provider allowlist, no compaction or goal runs, no pending runtime requests, and the snapshot must show that same turn as restart-interrupted. - `native-session-runtime.test.ts`: a new regression for an ACPX session that loses its own turn to a mid-execution `runnerd` restore, plus a negative case for a lost turn this execution never started. ## Verification - Red before the fix: `npx vitest run src/native-session-runtime.test.ts` failed `continues its own turn once when runnerd is restored mid-execution` with `NativeProviderTerminalFailure: Provider turn failed`, the same failure seen on staging. - Green after the fix: `native-session-runtime.test.ts` and `native-session-runtime.provider-turn.test.ts` pass (337/337). The existing `requires the control plane restart claim` case still refuses a recovered session without the claim. - `pnpm verify` (affected selection): see the CI results on this PR. - Live acceptance: after deploy, retry the affected staging tasks and confirm that a mid-turn `runnerd` restore leads to one continuation turn in the same sandbox instead of `native_provider_terminal_failed`. ## Risks - **Second executor.** The continuation can start only from the execution that opened the session and started the turn. It is not used for a recovered or adopted session without a claim. It runs at most once per run (`restartContinuationStarted`). The runner emits this code only after it proves the old provider process ended. - **Run starts.** This starts no new runs. It adds at most one turn to a run that would otherwise fail and schedule a fresh-sandbox retry. During a crash loop, `MAX_UNSTABLE_RUNNER_RESTORES` in the transport still fails the transport. - **Disk still full.** If the continuation fills the disk again, the second lost turn finds `restartContinuationStarted` set, and the run fails as it did before. The worst case is the current behavior. - **Not in this PR.** Paperclip's own footprint (about 3G of provider pack per sandbox, and a per-session pnpm store) and classifying a disk-full failure so it does not retry into the same wall. Both are follow-ups. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, browser, and a code-tracing subagent). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
57e85d0d10 |
fix(adapter-utils): wait for a replacement GitHub broker after a controller restart (#22209)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for work
> - Agents in sandbox tasks use managed `git` and `gh` launchers. Each launcher gets a GitHub credential from a broker for each command.
> - A controller restart stops the broker of a task. The provider in the sandbox continues to run. The restored controller then writes a replacement broker location to `broker.json`.
> - The launcher read `broker.json` one time only. It retried a transport failure for about 1.5 seconds. Then it ran the command without credentials.
> - Thus, commands in the restart window failed with "You are not logged into any GitHub hosts" or "could not read Username". Agents lost pull-request checks and pushes, but the GitHub connection was healthy.
> - This pull request makes broker-file launchers wait for a bounded time and read `broker.json` again before each retry.
> - The benefit is that GitHub commands continue with managed credentials through a controller restart.
## Linked Issues or Issue Description
No public issue exists. This is the bug description.
**What happened?**
A sandbox task ran `gh` or `git` while the controller restarted. The launcher wrote `Paperclip: GitHub broker_transport_unavailable; continuing without managed credentials.` Then `gh` wrote "You are not logged into any GitHub hosts", and `git` wrote "could not read Username". Private reads, pushes and pull-request commands failed. Failures occurred in many tasks at the same time, for some minutes.
**Expected behavior**
The launcher waits for the replacement broker for a bounded time. Then it uses the managed credential. If the broker does not return, the launcher continues without credentials and shows the same diagnostic as before.
**Steps to reproduce**
1. Write a broker-file launcher. Set `broker.json` to a closed local port.
2. Run `gh` through the launcher.
3. After 3 seconds, write a reachable broker location to `broker.json`.
4. The command ran without credentials before the replacement was written.
**Relevant logs or output**
`Paperclip: GitHub broker_transport_unavailable; continuing without managed credentials.` followed by `You are not logged into any GitHub hosts. To log in, run: gh auth login`.
## What Changed
- `packages/adapter-utils/src/github-launcher.ts`: Broker-file launchers retry for up to 60 seconds. Before each retry, they read `broker.json` again. A replacement broker is used when the restored controller publishes it.
- The launcher retries two failure types in this wait: a refused or failed connection, and an HTTP 503 answer. With HTTP/2, the sandbox gateway can continue to listen after its controller connection closes. It then answers `503 {"error":"bridge_unavailable"}`.
- HTTP 401 and 403 answers are real denials. The launcher does not wait for them.
- If `broker.json` cannot be read or parsed (for example during a rewrite), the launcher keeps the last broker location and continues the wait. If `broker.json` is missing, has no broker, or has an empty URL or token, the launcher stops the wait at once, because the access of the task ended. (When a replacement bridge cannot start, the controller writes empty values.)
- After the third failure, the launcher writes one line to stderr: it waits for the credential service to return.
- Launchers with an inherited broker URL keep the old short retry budget and the old 503 behavior. Their URL cannot change, so a longer wait cannot help.
- `packages/adapter-utils/src/github-launcher.test.ts`: Regression tests for three outage types (a closed port, a 503 `bridge_unavailable` gateway, and a partly written `broker.json`). Other tests remove `broker.json` or write empty values to it during the wait, and check that 401 and 403 answers do not wait.
- `doc/execution-github-identity.md`: One sentence describes the wait.
## Verification
- Failing before the first fix: `waits for a replacement task broker instead of running without credentials (closed port)` failed with `expected 'anonymous' to be 'reattached-run-credential'`.
- Failing before the second fix: the `(bridge unavailable)` and `(partly written broker file)` cases failed with `expected 'anonymous' to be 'reattached-run-credential'`. The `(closed port)` case passed.
- Failing before the third fix: `stops waiting for an unreachable task broker once its broker file is emptied` timed out after 20 seconds, because the launcher continued to wait. The `removed` case passed.
- Passing after the fixes: `npx vitest run packages/adapter-utils/src/github-launcher.test.ts packages/adapter-utils/src/execution-target.test.ts packages/adapter-utils/src/github-launcher-environment.test.ts server/src/services/heartbeat-github-launchers.test.ts server/src/services/native-runtime/native-github-access.test.ts` passed 138 of 138 tests in 5 files. `native-github-access.test.ts` includes the controller restart and launcher re-arm tests.
- `npx tsc --noEmit -p packages/adapter-utils` passed.
- I did not run the full `pnpm verify`. The local disk was too small for a full install.
- Note: Run these tests outside a managed sandbox, or remove the sandbox GitHub launcher from `PATH` and unset the sandbox broker variables. The sandbox values otherwise leak into the tests on `master` too.
## Risks
- If the broker does not return, a GitHub command that needs credentials now waits up to about 60 seconds (plus one 10-second request timeout) before it continues without credentials. Before, it waited about 1.5 seconds. Local Git commands do not ask the broker, so they do not wait.
- A broker that answers 503 for a long time (for example, when its credential lookup fails) also causes this 60-second wait. Then the launcher continues without credentials, as before.
- The launcher sends no credential in the new stderr line. The tests check that broker tokens do not appear in stderr.
- Low risk otherwise. The change is in the generated launcher source only.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution.
## Checklist
- [x] I have included a thinking path that traces from project context to this change
- [x] I have specified the model used (with version and capability details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
ee68098584 |
fix(runner): keep current task requests readable in OpenCode traces (#21584)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Company traces let operators compare each request with its reply. > - OpenCode limits each text field to 8 KiB. > - A fresh session can put old history before the current request. > - The limit can remove the current request from the trace. > - This change selects the current task text first and links the retained submission. ## Linked Issues or Issue Description Refs #18098 and #18699. Neither merged change selects the current task request. **What existing behavior does this improve?** OpenCode company traces can contain only part of the old session history. **Current behavior** The exporter clips the full model envelope from its start. A sampled trace has a useful HOLD reply but a request that ends inside old history. A truncation flag is not proof that the task failed. **Proposed behavior** Select the task prompt before the text limit. Remove a valid leading generated handoff packet from the excerpt. Link the full retained run event through the existing API. [Source pattern](https://www.braintrust.dev/app/Paperclip/p/Paperclip%20Staging/patterns/e6d8da04-ca3e-4bd9-bd90-737f7717a9e1). ### Hypothesis and thesis for a fix The baseline exporter spends its text budget on the envelope and old history. The new regression confirms this cause: the received OTLP input loses a short current request after a long handoff. Select the current request in the OpenCode projection before redaction and clipping. Keep storage and access checks with their existing owners. ## What Changed - Select task identity and prompt for known native envelopes. Put pending user messages first in continuation excerpts. - Omit only a valid leading generated handoff packet. Keep plain text and unknown formats on the existing path. - Add a relative run-events reference under the prompt capture switch. Readers must sign in to the source instance and page to the matching turn. - Keep raw tool argument values excluded. Keep redaction, opt-in, capture switches, company access and size limits. - Add exporter, proxy, installed-runtime and private-run retrieval tests. Fix the proxy test's session-directory lookup so it skips the output-custody directory. - Document the excerpt and full-event retrieval path. ## Verification - Baseline `6b6c94a4ea8f3d1b58767d67a7a2fc4ceaecda9c`: the new long-handoff regression failed because OTLP input did not contain the current request. - Same regression passes after the fix. Exporter, redaction and bundled proxy suites: 39 tests passed. - `PAPERCLIP_OPENCODE_QUALIFY=1 pnpm --dir packages/paperclip-runner exec vitest run src/drivers/opencode/company-observability-runtime.test.ts`: 2 passed. Real installed OpenCode 1.18.34 and real HTTP OTLP receiver; local SSE model fixture. Both capture settings pass. The model receives the full original submission. - Private-run API suite: 31 tests passed on base `340157d1d6ec01ad0fa55970e148c6cd332bbcb1` with these changes. Authorized readers retrieve a complete request over 8 KiB through pagination. Other readers receive 404. - Runner TypeScript source and test checks and TypeScript build passed. `git diff --check` passed. - `pnpm verify --explain` returned exit 2 and required broader CI. No full local-suite pass is claimed. - Initial harness attempts used the wrong Vitest working directory, lacked built plugin-sdk, selected the wrong proxy fixture directory, or expected 403 instead of the API's 404. These are not red regression results. The corrected checks above pass. - Review follow-up `dfe995a77f3eb3280a6b081b4df9428fac85f540` removes added code comments required by CONTRIBUTING.md. Exporter + installed OpenCode runtime suites reran: 30 tests passed, with the local SSE model and real HTTP OTLP receiver. `git diff --check` passed. The review thread is resolved. Greptile passed on this exact revision with confidence 5/5 and no actionable findings. Final-head typecheck, build, Runner and E2E checks passed; server test shards and the amd64 Runner image build remain in progress. No hosted model call or deployed recovery is claimed. ## Risks Known envelope excerpts change shape from serialized envelope text to readable task text. The handoff selector depends on the current generated packet format; unknown framing falls back to the full prompt excerpt. Long current requests still clip. Full-event access depends on source-instance permission and retention. Export remains best effort. The new reference grants no access and includes no credential. This PR is unmerged and not deployed. ## Model Used OpenAI GPT-6 through Codex, with reasoning, tool use and code execution. The exact serving variant and context size are not exposed to this session. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Final verification (2026-11-14): exact head `dfe995a77f3eb3280a6b081b4df9428fac85f540` has 60 successful checks, one neutral security scan, and five conditional skips (cache write, publication/attestation, incremental selection, Storybook paths). Applicable typecheck, build, general and serialized tests, Runner tests, E2E and both Runner image architectures passed. [CI](https://github.com/paperclipai/paperclip/actions/runs/43572758306), [Runner images](https://github.com/paperclipai/paperclip/actions/runs/43572758233), [Greptile](https://github.com/paperclipai/paperclip/runs/132380487679). Greptile 5/5, no unresolved actionable findings. Unmerged and not deployed. --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
33fac97cad |
feat(routines): ship the redesigned routine page and let live webhooks be tested again (#22205)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Routines start agent work on a schedule, from a webhook, or on demand > - The routine detail page split one routine across eight sections behind a section sidebar (overview, triggers, variables, secrets, delivery, runs, activity, history) > - People had to hunt through sections to see what a routine does and to change it, and a finished webhook could not be tested again without starting the routine > - This pull request makes the approved two-column routine page, one Edit dialog and one Webhook dialog the real routed page, and lets a live webhook go back into test mode > - The benefit is one page that answers what the routine does, when it runs, who runs it and what it made, with every change in one dialog ## Linked Issues or Issue Description **Problem** The routine detail page spreads one routine over eight sections and a section sidebar. Changing a routine means visiting several sections, each with its own save bar. A webhook that is already live cannot be tested again: the API only accepts `setupPending: false`, so testing a live webhook starts the routine. **Proposed solution** Ship the reviewed design (stories `routine-page-design`, `routine-edit-dialog-design`, `routine-webhook-dialog-design`) as the routed page in both UI shells, wired to the real API. Let `PATCH /api/routine-triggers/:id` accept `setupPending: true` for a live webhook so the next events are checked but never start the routine. **Alternatives considered** Keep the sections and restyle them. The owner rejected this: the section sidebar should go. ## What Changed - `/routines/:id` renders `RoutinePage` in both shells (`RoutineDetail.production.tsx` is removed). Status switch, Repeats rows, default agent, responsible user, project, Asks for, Secrets, Run rules, Managed by plugin, Instructions with Show all, copy and the comment count, and History. - History is paged: 20 tasks per page from `GET /companies/:id/issues?originKind=routine_execution&originId=…&sortField=created&sortDir=desc&limit=21&offset=…`, with a real Load more. Coalesced runs show as "folded into a task". - A failed refetch keeps the loaded page on screen (`useQueryView`); a History failure shows `QueryErrorState` in place. - Header: Edit, "…" (Version history, Audit log, Archive / Restore) and Run now. In the streamlined desktop shell they sit in the breadcrumb toolbar; elsewhere above the page. - Version history (`/routines/:id/history`, restore and restored-webhook keys kept) and Audit log (`/routines/:id/activity`, `RoutineAuditActivity`) open as sub-views with a way back. Old section addresses and `?tab=` redirect to `/routines/:id`. - Edit dialog saves title, instructions, variables, secrets, agent, project and responsible user in one request against the revision the dialog opened with (save conflict shows "changed while you were editing"). The first schedule is created, changed or removed after that. Priority and delivery settings are never sent, so saved values stay. - Webhooks are created, changed, tested and removed (with Undo) right away from the Edit dialog, with the Webhook dialog nested inside it. Closing the Webhook dialog ends setup or test mode. A webhook left in test mode shows "Testing · events don’t run" on the page and offers Finish testing. - Responsibility (only with `enableResponsibilities`): the page shows direct and through-project responsibilities from the link lookup; the dialog links or unlinks the direct one. With the flag off nothing is fetched or shown. - The routines list creates routines with the same dialog in create mode, filed in the open folder, and opens the new routine page. - Server: `setupPending: true` on a live webhook enters test mode (planned by a pure `planTriggerUpdate`, which also gives the activity action) (422 for other trigger kinds; 409 for a disabled or removed webhook or an archived routine). Test deliveries keep the last real delivery as `lastWebhookDelivery.previous`, and finishing testing restores it. Activity `routine.trigger_test_started`. - Additions to the reviewed design, from review, so no capability is lost: the schedule popover has Pause/Resume; standing-check and API rows open a small popover with Pause/Resume and Remove; removing a trigger from the page leaves a "… removed. Undo" line under Repeats. Stories: `StandingCheckOpened`, `ScheduleTriggerPaused(Opened)`, `RemovedWithUndo`. - Save is several requests (routine, schedule, responsibility). It changes only the schedule the form opened with, records each finished step, and a partial failure says what was saved and that saving again finishes it. The dialog cannot be dismissed while saving. Failed reads show a Retry state, never empty choices. - Removed: the routine section sidebar and contextual sidebar, the trigger wizard, trigger cards, save bar, section components and their tests. - Storybook: the three routine stories moved to `stories/routines` as current production stories, a new story mounts the routed page against a fixture API, and stories that used the old page were updated or removed. ## Verification - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/routines-e2e.test.ts` (17/17) and `src/__tests__/routines-service.test.ts` (105/105). - `pnpm exec vitest run` on the routine page, routines list, routine form, webhook instructions, Layout, shell navigation, audit and editor tests: 275 tests pass. - `cd ui && npx tsc -p tsconfig.json --noEmit`, `node scripts/check-token-gates.mjs`, `node scripts/check-maps.mjs`, `node scripts/storybook-catalog.mjs --check`: pass. - `pnpm verify` exits 2 (global CI input changed); required CI supplies the broad coverage. - Manual: an isolated worktree instance (`pnpm paperclipai worktree init --empty`, `pnpm dev`) with a seeded routine. Headless Playwright: an old `/triggers` address redirects, no section sidebar, History shows 20 then 23 after Load more, the schedule popover opens, pause and resume, Edit → Add webhook → created key → Finish, title save, Test webhook → Finish testing, Version history, Audit log shows "Started testing a webhook", phone width has no horizontal overflow, and Create routine from the list opens the new page. No console errors or failed API calls. ## Risks - Behaviour change: the section pages are gone. Old links redirect to the single page. - The delivery-setting editors (concurrency, catch-up, activity gate) and priority are removed from the UI. Saved values stay, and the API still accepts them. - The create dialog no longer offers a folder picker or delivery settings. A new routine goes into the folder the list is showing and takes the default settings. - Replace key in the Webhook dialog acts at once, as in the reviewed design. The old confirmation is gone. - No migration. `lastWebhookDelivery.previous` is an optional field inside the existing jsonb column. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with tool use (shell, file edits, headless browser) and subagents for the server change and the Storybook move. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com> |
||
|
|
651749bdb4 |
feat(connections): AWS connector with credentials minted per connection (#22195)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use outside services through connections, and the control plane holds each connection's credentials > - Companies want agents to "do things on AWS" with exactly the permissions they choose, without Paperclip storing long-lived AWS keys or rebuilding the AWS API > - AWS hosts an MCP server that runs any AWS API call in its own sandbox, and it accepts a one-hour bearer token that can be minted from IAM credentials > - This pull request adds an AWS connection that mints that token for each connection at call time. The role method proves the connection with the company's workload identity issuer (#22083), so no AWS key is stored > - The benefit is that each AWS connection carries its own role and permissions, AWS enforces them, and agents never see any AWS credential ## Linked Issues or Issue Description Refs #22083 (workload identity issuer) and #22191 (spike findings). **Subsystem affected** Connections (tool access), tool gateway, shared app definitions, instance settings. **Problem or motivation** Paperclip has no way to connect AWS. AWS's hosted MCP server needs a bearer token from AWS Sign-in, minted from IAM credentials. No existing credential path mints a header at call time from a role or key. **Proposed solution** Methods can declare `credentialMinter: "aws_mcp"`. The gateway and connection health checks mint the `Authorization` header at call time, and they share one in-memory cache per connection and grant (about 55 minutes). There are two methods: - Role (`AssumeRoleWithWebIdentity` with a Paperclip-signed connection token). - Access key (the key directly, `GetFederationToken`, or `AssumeRole`). Read-only connections add `ReadOnlyAccess` and `AWSMCPSignInOAuthAccessPolicy` as session policies, so AWS refuses changes. The feature is behind the `enableAwsConnector` experimental setting. **Alternatives considered** - Run AWS's `mcp-proxy-for-aws` process on the control plane. Rejected: it adds a Python runtime and processes, and gives nothing the token exchange does not. - Put credentials in the agent sandbox and use the AWS CLI. Deferred: there is no per-call governance, and every sandbox would need the CLI. - Add a new `credentialSource`. Rejected: it needs a migration, and the `vercel_connect` database rules do not fit stored access keys. ## What Changed - `packages/shared`: - `credentialMinter` on connection methods. The validator requires `mcp_remote` and `api_key`, and does not allow `keyPlacement` or another credential source. - The `aws` app definition (two methods, reviewed tools, `mcpSessionRequired`, experimental key). - The `enableAwsConnector` setting in the catalog, types and validators. - `aws` added to the connectable apps. - `server/src/services/connectors/aws/mcp-credentials.ts`: - Settings parsing and checks. The URL must be AWS's endpoint for the saved region, and the role ARN must be valid. - The minter: role or key session, read-only session policies, Sign-in exchange, cache keyed on settings, key references and status, in-flight de-duplication, eviction. - A plain-language error mapping that never shows AWS's own text, because that text can contain account IDs and ARNs. - Gateway (`resolveCredentialHeadersUnrecorded`), credential access (`resolveCredentialHeaders`), catalog discovery and health-failure mapping: - The AWS branch. - After a 401, the gateway evicts the token and mints again, then requires an explicit retry (no replay). Discovery lists again. - Setup: - Minted methods may save a draft without contacting the provider. The role must trust a connection that already exists. - Saving an AWS role draft publishes the company's issuer, so AWS can validate it when the customer registers it. - `workload-identity.ts`: a draft connection can get a token, so setup can test it. Disabled, archived or switched-off connections still get none. - `server/package.json`: `@aws-sdk/client-sts` and `@aws-sdk/client-signin`. The lockfile is left to the refresh workflow. - Artwork: AWS light and dark marks from LobeHub's MIT icon set (already licensed in the repo). The manifest entry passes the brand checks. - `scripts/ingest-app-definitions.mjs`: minted methods are exempt from the `keyPlacement` requirement. The override source is `scripts/app-definition-overrides/aws.json`. Permission reviews are added. - UI: the experimental settings toggle, in alphabetical position. - Docs: `doc/connections/AWS.md`, the connections index, the issuer API doc (draft rule), and the plan's phase table. ## Verification - `server/src/services/connectors/aws/mcp-credentials.test.ts` (7 tests) covers these items: - Both methods and the read-only policies. - Caching, revision, forced refresh, expiry and eviction. - Concurrent de-duplication. - The error mapping, with no AWS text leaking. - Settings validation, including the URL and region check and the rule that an unknown access level means read only. - `server/src/__tests__/aws-mcp-connector.test.ts` (3 tests, real setup, catalog and gateway code with a fake AWS and a session-requiring fake MCP server) covers these items: - The setting gates setup. - The access key is never sent as a header or stored in config. - A cached token is reused. - After a 401, a fresh token is minted and the call is not replayed. - Role draft-then-resume publishes the issuer. - The signed token has the right `iss`, `sub` and `aud`. - An AWS refusal shows a plain health message without the account ID. - Red/green: - Removing the gateway hook fails the access-key test. - Turning off `mcpSessionRequired` fails both integration tests. - Removing draft support for minted methods fails both integration tests. - Restoring each change passes again. - Nearby suites: `tool-gateway-service`, `tool-access-service`, `remote-mcp-connectors`, `instance-settings-service`, `workload-identity`, plus the new files. 775 of 775 pass. - Shared `app-definitions.test.ts` passes (42), including new `credentialMinter` schema tests. UI `InstanceExperimentalSettings` (63) and the brand asset tests pass. `check-app-brand-assets` validates 112 identities. - Typecheck is clean for `packages/shared`, `server` and `ui`. The only UI errors are in Storybook's generated catalog files, which this worktree has not built. - **Real AWS** (Paperclip dev account, integrated code path, issuer behind a temporary public tunnel): - Access key, read only: 8 tools listed. `run_script` `ListBuckets` succeeded in 8.9 s on a cold sandbox. AWS refused `CreateBucket` ("no session policy allows"). - Role: the draft was saved without contacting AWS, and the issuer was published. After an IAM provider and a role trusting only that connection were created, resuming setup listed 8 tools. `ListBuckets` succeeded in 12.8 s. The role's own permissions refused `CreateBucket`. - This run found two bugs the fakes did not: AWS needs MCP sessions for calls, and the role method needs draft-first setup with the issuer published. Both are fixed and both now have tests. - All IAM users, keys, roles, providers and buckets were deleted, and a listing confirmed it. - Not run: Paperclip Cloud staging (the setting is off by default), and `AssumeRole` from an access key with a role ARN against real AWS (unit tests only). ## Risks - The feature is off by default, behind `enableAwsConnector`. No migration. - New dependencies `@aws-sdk/client-sts` and `@aws-sdk/client-signin` are in the existing `@aws-sdk` family (the server already uses `client-s3`). - Minted tokens are held only in process memory. A restart mints again. A cached token can outlive a deactivated key by up to an hour, unless AWS returns 401, which evicts it. - `aws___run_script` is classified as a write, so the normal approval and ask-first policy applies. Read-only connections rely on AWS session policies. - The guided setup screen and the CloudFormation template are not in this PR. Setup uses the generic form and the documented draft and resume steps. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, AWS SDK for JavaScript against the Paperclip dev AWS account, a Cloudflare quick tunnel, an exploration subagent). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
f0bd99ba8a |
fix(recovery): wait out a sandbox the provider could not start, with no Retry (#22194)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A task that runs in a sandbox environment first gets a lease from the environment provider (for example Daytona) > - Sometimes the provider creates the sandbox but cannot start it. Daytona then puts the sandbox in its `error` state > - The Daytona plugin deletes that failed sandbox and rethrows the provider error. The error has no HTTP status and no errno, so the host cannot tell that it is a provider-side failure > - The run fails with `setup_failed`, and the task rests on "Retry when ready". No agent work had started, and a fresh sandbox works, so a person must click Retry for something the system can do itself > - Recovery must just work, and the target for runs that need Retry is 0% > - This pull request makes the plugin report a removed sandbox that the provider could not start as structured evidence (the step and the provider state). The host classifies it as a transient provider failure. The task then uses the existing bounded retries and the provider-outage wait from #22139 > - The benefit is that a provider start failure delays the task by seconds instead of stranding it on Retry ## Linked Issues or Issue Description Refs #22139 (the provider-outage wait lane that this failure now reaches). Refs #22128 (setup failure after work; this failure happens before any work, so that path did not apply). **What happened?** In a restart-chaos wave with graceful release swaps on 2026-11-18, two tasks started a run at 14:51:15Z and 14:51:24Z. Both runs failed at 14:51:53Z with `setup_failed` and `failureCause: lease_acquire_failed`. The cause was `Sandbox <id> failed to start with status: error, error reason: null` from the Daytona SDK, for two different sandboxes at the same moment. Both tasks rested on Retry. A Retry click started each task again, and both tasks completed. **Expected behavior** A sandbox that the provider cannot start is a provider failure before any agent work. Paperclip deletes it and tries again with a new sandbox, with no Retry. If the provider keeps failing, the task waits for the provider without a Retry, and a person gets a working Retry only after the 30-minute ceiling. **Steps to reproduce** 1. Make the Daytona create call fail while the new sandbox is in the provider's `error` state. 2. Assign a task to an agent that uses that environment. 3. The run fails with `setup_failed`, and the task rests on Retry. ## What Changed - Plugin SDK (`environment-creation-cleanup.ts`, `environment-acquire-error.ts`, `index.ts`): new `PluginEnvironmentAcquisitionError`. It carries the acquisition diagnostic (step, elapsed time, budget, provider state) for a failed allocation that the provider already removed, with no cleanup envelope. The acquire RPC error data (`paperclip/environment-acquire-error/v1`) now carries this diagnostic. `readEnvironmentAcquisitionDiagnostic` reads it from that envelope. The existing cleanup envelope path is unchanged. No provider text crosses the RPC. - Daytona plugin (`plugin.ts`): `destroyFailedCreation` returns the state of the sandbox that it deleted. When a create fails without an HTTP status and the deleted sandbox was in the `error` state, the plugin throws `PluginEnvironmentAcquisitionError` with `providerState: "error"`. A `build_failed` sandbox (a deterministic snapshot build failure) and any other state keep the original error. - Server (`environment-runtime.ts`): the acquire path records the diagnostic for this run also when the error has no cleanup envelope. A cleanup envelope for another run, company or environment still records nothing. - Server (`environment-provider-unavailable-error.ts`): an acquisition diagnostic with `providerState: "error"` is the transient reason `provider_start_failed` ("the provider could not start the sandbox"). It becomes `EnvironmentProviderUnavailableError`, so the run uses the two bounded retries and then the provider-outage wait lane (one probe per environment, 30-minute ceiling). - `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed pins for the changed SDK sources (generated by `node tests/runner-e2e/source-sdk-public-inputs.mjs <sha> --write`). Module boundaries: the change to the shared SDK contract is additive. The Daytona plugin owns the provider state. The host reads only the closed diagnostic fields. A plugin that does not use the new class behaves as before. ## Verification - `packages/plugins/sandbox-providers/daytona`: `npx vitest run src/plugin.test.ts -t "failed sandbox creation cleanup"` (37 passed). New: "reports a sandbox that failed to start as a removed allocation with its observed step" (red before the plugin change, green after) and "keeps the create error when the removed sandbox was build_failed / started". - `packages/plugins/sdk`: `npx vitest run tests/environment-acquire-error.test.ts tests/environment-creation-cleanup.test.ts` (50 passed). New: the diagnostic crosses the real worker RPC without provider text, and forged or unstructured envelopes give no diagnostic. - `server`: `npx vitest run src/services/environment-provider-unavailable-error.test.ts src/__tests__/environment-acquisition-diagnostics.test.ts` (74 passed). New: the reason is `provider_start_failed` with a transient provider failure, and a diagnostic that was not recorded for this run is not retried. - `server`: `npx vitest run src/__tests__/environment-runtime.test.ts -t "provider could not start|retains uncertain plugin creation"` (12 passed). New: "records the step of a sandbox the provider could not start and removed" for a worker error (red before the runtime change, green after) and for a forged error (not recorded). - `server`: `npx vitest run src/services/__tests__/run-failure-diagnostics.test.ts src/__tests__/heartbeat-process-recovery.test.ts -t "provider|acquisition|diagnostic"` (167 passed). - Typecheck: `server` `tsc --noEmit`, `pnpm run typecheck` in `packages/plugins/sdk` and in the Daytona plugin all pass. - `pnpm verify` exits 2 (the SDK input registry is a global CI input). Required CI supplies the broad coverage. ## Risks - **Automatic retries for a deterministic start failure.** If a provider image or configuration made every sandbox go to `error`, the task now waits in the provider-outage lane instead of resting on Retry at once. The lane uses one probe per environment on a 1, 2, then 5 minute backoff, and it hands the task to a person with a working Retry after 30 minutes. The aggregate automatic-run brake is unchanged. `build_failed` is not retried by this change. - **Shared SDK contract.** The new field is additive. An older host ignores it, and the run fails as before. - No database migration. No UI change. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, used in Claude Code with tool use (shell, file edits) and extended reasoning. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
3c460f20cc |
feat(analytics): ask EU, UK and Swiss visitors before Cloud browser analytics (#22186)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Paperclip Cloud can send browser product analytics and session replays to PostHog. Self-hosted installs never do this. > - Today, browser analytics starts for every Cloud visitor after the page settles. > - Visitors in the EU, the EEA, the UK and Switzerland must agree before analytics cookies and session recordings start. > - This pull request adds a consent step for these visitors and a switch in the user's profile settings. > - The benefit is that Cloud analytics follows the owner decision: ask in Europe, keep the current behavior elsewhere, and let every user change the choice. ## Linked Issues or Issue Description **Subsystem affected** Paperclip Cloud browser product analytics (`ui/src/lib/analytics`, `ProductAnalyticsGate`, the session route, and Profile settings). **Problem or motivation** Browser analytics and session replay start for every Cloud visitor without a choice. EU, EEA, UK and Swiss visitors must consent first. The privacy policy draft also says that users can change the choice in settings. No such setting exists. **Proposed solution** Ask visitors in the EU, the EEA, the UK and Switzerland with a small bottom banner (Accept or Decline). Do not load posthog-js before they accept. Treat Do Not Track and Global Privacy Control as a decline for these visitors. Keep the choice in `localStorage`. Add a "Product analytics" switch to Profile settings for every user when browser analytics is on. **Alternatives considered** A server-side country from a trusted edge header. Paperclip Cloud has no such header today: Cloudflare records are DNS-only, so no `CF-IPCountry` arrives, and the Railway edge adds no country header. This PR supports an optional header (`PAPERCLIP_POSTHOG_COUNTRY_HEADER`) for a future edge, and uses the browser time zone until then. ## What Changed - `packages/shared`: `browserAnalytics` has a new optional `consentRequired: boolean | null`. - `packages/shared/src/analytics-consent.ts` (new): the one region policy. `countryRequiresAnalyticsConsent` (EU and EEA with outermost regions and Svalbard, GB with the Crown Dependencies and Gibraltar, CH) and `timeZoneRequiresAnalyticsConsent` (`Europe/*`, EU, EEA and UK zones outside Europe, and unknown zones such as `UTC` or `Etc/*`). The server and the UI both use it. - `server`: `resolveBrowserAnalyticsConfig` sets `consentRequired` from the header that `PAPERCLIP_POSTHOG_COUNTRY_HEADER` names. No header or an unknown code (`XX`) gives `null`. - `ui/src/lib/analytics/consent.ts` (new): decides `granted`, `denied` or `ask`. Order: for a visitor who must consent, Do Not Track or Global Privacy Control gives `denied` (also over a stored Accept); then the choice made on this page; then the stored choice; then the region (server value, else browser time zone). The choice is in `localStorage` key `paperclip.analyticsConsent`. All storage access is in `try/catch`. A cross-tab `storage` event updates the page. - `ProductAnalyticsGate`: one effect calls `syncProductAnalytics(config, consent)`. Shows `AnalyticsConsentBanner` when consent is `ask`. Accept loads posthog-js at once, without a reload. - `product-analytics.ts`: new `syncProductAnalytics`. It starts, opts in, opts out (`opt_out_capturing()` and `stopSessionRecording()`) or cancels a pending load. Any consent other than `granted` stops analytics. If consent is withdrawn while the script downloads, `init()` does not run until a later opt-in. - `AnalyticsConsentBanner` (new): a labelled bottom region with plain copy, a privacy policy link, and Decline and Accept buttons (shared `Button`). The copy says that recordings hide what you type and your messages, documents and connected accounts, but may show page names like task titles. It does not block the page. On mobile it sits above the bottom navigation. - `ProductAnalyticsSetting` (new) in Profile settings: a "Product analytics" switch (shared `ToggleSwitch`). It shows only when browser analytics is on for the instance. When GPC or DNT blocks analytics, it is off and disabled and says why. - `doc/cloud-browser-analytics.md`: new Consent section (signal, behavior table, storage key, how to reset) and the new variable. - `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed for the changed shared validator. ## Verification - Red/green: the 7 new `ProductAnalyticsGate` consent tests fail against the master gate (7 failed, 3 passed). The 5 review-fix tests (failed write with working read, cross-tab change, decline during script download, granted -> ask from another tab, granted -> ask from a session refresh) fail on the first commit (5 failed, 16 passed). All pass now. - `cd ui && npx vitest run src/lib/analytics src/components/ProductAnalyticsGate.test.tsx src/components/AnalyticsConsentBanner.test.tsx src/components/ProductAnalyticsSetting.test.tsx src/pages/ProfileSettings.test.tsx`: 267 tests pass. - `cd server && npx vitest run src/__tests__/cloud-posthog-browser.test.ts src/__tests__/auth-routes.test.ts src/__tests__/auth-session-route.test.ts`: 87 tests pass. `packages/shared` `analytics-consent.test.ts` passes. `tsc --noEmit` for `ui`, `server` and `packages/shared` shows no new errors. - `pnpm verify` exits 2 (a doc is a global CI input). Required CI gives the broad coverage. - Real check in headless Chromium. I ran a local Cloud-managed instance (external local PostgreSQL, `PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN`, `PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`). `PAPERCLIP_POSTHOG_HOST` pointed at a local capture server, not PostHog. The capture server served a small stand-in for `array.js` that sets a `ph_*` cookie and `localStorage` key and posts `/e/` events. I set the visitor region with the browser time zone: | Visitor | Result | | --- | --- | | `Europe/Berlin`, no choice, 18 s wait | Banner shows. 0 `/_ph` requests. No `ph_*` cookie or storage key. | | Then Accept (keyboard Enter) | Banner closes. `GET /_ph/static/array.js` and `POST /_ph/e/` in 3 s. Key is `granted`. After reload: no banner, events continue. | | `Europe/London`, Decline, wait, reload, wait | No banner. 0 `/_ph` requests. No `ph_*` cookie or storage key. Key is `denied`. | | `Europe/Zurich` with Global Privacy Control | No banner. 0 `/_ph` requests. No `ph_*` cookie or storage key. | | `America/New_York` | No banner. posthog-js loads after the page settles, as before. | | Profile settings switch (US) | Shows on. Off: client is opted out at once. On: opt-in, events continue. | - I ran the browser check again after the review fixes, with the same results. - Screenshots (banner light, banner dark, mobile 375 px light and dark, settings switch): see the PR comment. - Cold load (local dev server, fresh browser context per run, median of 7, ms): | Build | Time zone | FCP | DOMContentLoaded | load | | --- | --- | --- | --- | --- | | master | New York | 728 / 724 | 687 / 684 | 689 / 686 | | this PR | New York | 748 / 724 | 708 / 684 | 710 / 686 | | master | Berlin | 740 | 694 | 697 | | this PR | Berlin | 756 / 724 | 716 / 684 | 718 / 686 | The second round gives the same medians for master and this PR. The first-round difference is noise. The consent code adds no request and no load-time wait. ## Risks - Region by time zone is approximate. It asks some visitors outside the EU (for example `Europe/Istanbul`, or `UTC` browsers). This is the safe direction. - A forged country header (only when `PAPERCLIP_POSTHOG_COUNTRY_HEADER` is set) changes only the default for that visitor's own browser. - The choice is per browser. A user on a new browser sees the banner again (in consent regions). - Visitors in consent regions now send no browser analytics until they accept. Expect fewer EU/UK sessions in PostHog. - Self-hosted installs: no change. They get no `browserAnalytics` config, so no banner, no switch and no load. ## Model Used - Claude Opus 5.5 (claude-opus-5-5), Anthropic, used through Claude Code with tool use (shell, file edits, headless browser). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
2a43fe3e34 |
feat(telemetry): add company_id to Cloud direct events from background work (#22183)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Paperclip Cloud sends server telemetry straight to PostHog (`server/src/services/posthog-direct/`) > - Request events get `company_id` from the request context. Background events have no request. > - So `agent.task_run`, `routine.run`, `connection.invoked`, and other background events arrive with `stack_id` but without `company_id`. On staging, 66 of 66 `agent.task_run` events had a null `company_id`. > - Without `company_id`, product analytics cannot split agent and routine activity by company. > - This pull request lets each background emit site name the company of the entity that it reports on. Only the direct PostHog transport reads that company. > - The benefit is that Cloud background events carry `company_id`, and the self-hosted collector output does not change. ## Linked Issues or Issue Description Refs #22006 **Subsystem affected** Server telemetry: Cloud direct delivery to PostHog (`server/src/services/posthog-direct/`) and the server emit sites for background events. **Problem or motivation** Cloud direct events from background work have no `company_id`. Heartbeat runs, scheduled routines, connection invocations, and interaction updates do not run inside an HTTP request, so the request context gives no company. On paperclip.staging, all 66 sampled `agent.task_run` events had `company_id` null. **Proposed solution** Add a small AsyncLocalStorage scope, `withTelemetryCompany(companyId, fn)`, in `server/src/telemetry-company-scope.ts`. Each background emit site wraps its typed `track*` call with the company id of the row that it already has. The direct transport reads the scope at track time, through the existing `captureEventContext()` seam. A live request company still wins. The collector path never reads the scope. **Alternatives considered** 1. An optional context argument on the shared `track*` helpers. This changes the public helpers in `@paperclipai/shared` for a Cloud-only value, so I did not use it. 2. A scope around each whole work unit (heartbeat run, routine run, invocation). The emit calls are fire-and-forget and are spread across many modules, so it is easy to miss one or to leak a company into other work. A scope at the emit site is narrow and explicit. 3. Let the transport look up the company in the database. The transport must not query the database. **Roadmap alignment** This completes the Cloud direct PostHog work from #22006. It does not change the telemetry contract. ## What Changed - Add `server/src/telemetry-company-scope.ts`. It has `withTelemetryCompany(companyId, fn)` and `scopedTelemetryCompanyId()`. With no company id, it calls `fn` directly. - `capturePostHogEventContext()` uses the scoped company when no live request gives a company. The request company, user, and session behave as before. - Wrap these emit sites with the company of their entity: - `agent.task_run` (`emitAgentTaskRun`, `emitAgentTaskRunById`; `companyId` is now part of the run that the function reads). This covers heartbeat, native runtime, recovery, run-dispatch, and watchdog callers. - `routine.run` (`routineService` dispatch, which covers scheduler, webhook, and manual runs) - `agent.first_heartbeat` (heartbeat agent status) - `connection.created`, `connection.updated`, `connection.invoked` - `interaction.created`, `interaction.resolved` - `agent.task_completed` (issue route; the issue company is the fallback when the request gives no company) - Request-only events (`project.created`, `goal.created`, `agent.created`, `routine.created`, `skill.imported`) keep the request context. `server.started` and `error_handler.crash` are not company-scoped. Dynamic plugin and `question_response.delivery` events are not in the contract, so the direct path drops them. - Update the "Cloud Direct Delivery" section of `packages/shared/src/telemetry/README.md`. Design note on module boundaries: the scope lives beside `server/src/telemetry.ts`, not inside `posthog-direct/`. Emit sites do not import the transport, and the transport does not know which services exist. The shared telemetry package does not change. ## Verification - Red/green: with the source changes removed, these 4 new tests fail. With the changes, they pass. - `agent-task-run-telemetry.test.ts`: `emitAgentTaskRun` and `emitAgentTaskRunById` track in the run company scope. - `routine-run-telemetry.test.ts`: a routine run tracks in the routine company scope. - `posthog-direct-telemetry.test.ts`: on Cloud, background `agent.task_run` and `routine.run` (also after an `await`) carry `company_id`, and an unscoped event does not. - `posthog-direct-telemetry.test.ts`: a live request company wins over the scope, and the scope fills the gap when the request has no company. - Red/green per emit family: the tests for `connection.created`, `connection.updated`, `connection.invoked`, `interaction.created`, `interaction.resolved`, `agent.first_heartbeat`, and `agent.task_completed` assert the company scope at track time. With the emit-site wrappers removed, all 7 assertions fail. - New guard test: on self-hosted, a scoped `agent.task_run` and `routine.run` produce a byte-identical collector envelope with no `company` text. - `cd server && npx vitest run` on 16 telemetry, PostHog, routine, heartbeat status, interaction, and connector test files: 408 passed. - `pnpm --filter @paperclipai/server typecheck`: passed. - Local check with a real `posthog-node` client sent to a local capture server (never real PostHog), embedded Postgres, and a real `routineService.tickScheduledTriggers()` tick plus `emitAgentTaskRun`: - Cloud mode: the captured `routine.run` (`source: schedule`) and `agent.task_run` both had the seeded `company_id`, plus `stack_id` and `environment`. `server.started` had no `company_id`. - Self-hosted mode: the collector body from this branch and from `origin/master` are identical after I normalize random ids and timestamps. - I did not boot a full Cloud-managed server, because it needs S3 and an external Postgres. The check above uses the same server modules and the real PostHog client. ## Risks - Privacy review: this is a Telemetry change under `rules/data-paths.mdc`, so I request a privacy review. Background Cloud events now send the real Paperclip `company_id` to PostHog. #22006 already approved `company_id` as a Cloud direct property for request events. This PR only fills it for background events. It adds no new property, dimension, or event, so the generated contract does not change. `packages/shared/src/telemetry/README.md` is updated in this PR. - Low runtime risk. The self-hosted collector path does not read the scope, and a test proves its output does not change. - On Cloud, more events now have `company_id`. No event loses a field. - If a request with a company tracks an event for an entity in a different company, the request company wins. This is the same as before this change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, and test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
1c556d5340 |
fix(native): never rest a task blocked on the agent's own blocker (#22140)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - A native run ends with one semantic report. A `paperclip_block`
report names a blocker, its owner and the unblock action
> - The status arbiter binds a task-wide blocker. When the owner is not
a person, it binds the blocker to the same agent and wakes that agent
> - The dispatcher refuses those self-wakes
(`chat_control_recovery_proof_unresolved`), because only continuation
and retry effects are proof for a native wake. The task then rests
blocked with no owner, no wake and no Retry
> - #21959 continues a system blocker in a fresh session, but only for
the reason codes `environment_unavailable` and `tool_unavailable`. A
restart-chaos rerun showed the same dead end with the reason code
`tool_output_failure`
> - This pull request makes sure that a blocker that the agent reports
for itself always has a next owner: the automatic environment lane, one
bounded self-continuation, or a person with a Retry that works
> - The benefit is that no task rests blocked with nobody to act, and no
path wakes the agent in a loop
## Linked Issues or Issue Description
Refs #21959
**What happened?**
A native OpenCode run (DeepSeek) said that every tool call returned the
text "cryptic". It reported `paperclip_block` with owner `{kind:
system}`, scope `task_wide`, reason code `tool_output_failure`, and an
unblock action about the tool-output failure. The run succeeded with
disposition `blocked`. The arbiter bound the blocker to the same agent
(`task_wide_blocker_bound`). The `notify-owner` wake coalesced, and the
`blocker-owner` wake was skipped as
`chat_control_recovery_proof_unresolved`. The task rested blocked
(`needs_attention`, 0 blockers), with no Retry and no wake. An earlier
rerun showed the same shape with reason code `environment_unavailable`,
which #21959 fixed for those two codes only.
**Expected behavior**
A blocker that the agent reports for its own tools or environment is a
harness problem. Paperclip continues it automatically, with a bound. A
blocker that the agent says it owns gets one fresh session. A blocker
that needs a person goes to a person, with a clear prompt and a Retry
that starts the task again. Nothing is left with nobody.
**Steps to reproduce**
1. Run a native task. Make the agent call `paperclip_block` with owner
kind `system`, scope `task_wide` and a reason code other than
`environment_unavailable` or `tool_unavailable` (for example
`tool_output_failure`).
2. See the decision `task_wide_blocker_bound` with the agent as the
unblock owner.
3. See both owner wakes refused, and the task blocked with no Retry.
**Paperclip version or commit**
`master` at
|
||
|
|
9e1a85fb46 |
fix(runner): accept a new controller when the listener's controller goes silent (#22088)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - On Daytona, the Paperclip server connects to a Runner that listens inside the sandbox, through the Daytona proxy > - A listening Runner accepts the next controller connection only after its current connection closes > - When the network path broke without a close, the Runner kept a dead socket and never accepted the new server after a release swap > - This pull request makes a listening Runner treat a controller that sends nothing for 90 seconds as gone, and listen again > - The benefit is that live runs survive a network outage that ends near a release swap, instead of losing their session and restarting fresh ## Linked Issues or Issue Description **What happened?** In a restart-chaos wave (201 tasks, 6 graceful release swaps), the host could not resolve Daytona hosts for about 12 minutes. Swap 4 happened at the end of that outage. The new server tried to reattach to 16 live runs. It reached none of them: all 16 were given up after 66 to 75 seconds (`reattach phase ended`, `authenticated: 0`, `givenUp: 16`). Each run then failed its three same-run resumes with `runner_ingress_unavailable` and continued in a fresh run. Six tasks showed a brief Retry banner, and the fresh runs repeated work. A sandbox snapshot taken 11 seconds after the swap shows the cause. The Runner process was alive. Its listening socket had 24 connections in the accept backlog and about 25 `CLOSE-WAIT` connections with an unread upgrade request. The Runner held one established connection from the Daytona proxy, with empty queues. Its saved state showed `reconnectCount: 0`, and no run event had arrived since the outage started. The Runner was waiting on a dead connection and did not call `accept` again. **Expected behavior** The server already pings the Runner every 20 seconds and drops a silent Runner after 90 seconds (#19407). The Runner side must do the same: a listening Runner that receives nothing from its controller for 90 seconds closes that connection and accepts the next one. **Steps to reproduce** 1. Start a Runner in listener mode and connect a controller. 2. Break the path between the controller and the Runner without a TCP close (for example, a proxy that keeps the sandbox-side socket open). 3. Connect a second controller. See that the Runner never accepts it. **Paperclip version or commit** master `ca34aca777` (wave) and `f5f60cfcb2`. ## What Changed - `AuthenticatedTransport` records when it last read any frame (text, ping, or pong). - On a listener-mode transport, a control read returns a transport error when no frame arrived within `DurableRunnerConfig::controller_silence` (default 90 s). The Runner then takes its existing disconnect path: it records a diagnostic, closes the socket, and accepts the next controller within its reconnect grace. A dial-mode transport is unchanged. - The silence rule applies only to steady-state control reads (`receive_json` and `receive_queued_json`). The welcome read during connection setup keeps its own deadline and timeout message, and the silence window restarts once the welcome validates, so a slow welcome is never reported as controller silence (which, after `auth_response`, would fail a bootstrap closed). - `DurableRunnerConfig::validate` rejects a `controller_silence` outside 100 ms to one hour, so a zero window cannot cause a tight reconnect loop. - `DURABLE_TRANSPORT.md` states the rule. ## Verification - New test `listener_accepts_a_new_controller_after_the_current_one_goes_silent` runs the real durable Runner loop in listener mode. An authenticated controller goes silent. A replacement controller authenticates with the lease and sends `runner.shutdown`. The Runner executes it once and exits cleanly. Red: with the silence branch disabled, the replacement is never accepted and the test fails. Green with the fix. - New test `listener_controller_pings_keep_an_idle_connection`: a controller that sends only WebSocket pings (every 400 ms, 1 s window, 2.5 s run) never triggers the silence error. Red when `last_inbound` is refreshed only on text frames. - New test `listener_welcome_timeout_is_not_reported_as_controller_silence`: with a 100 ms window and a lease-authenticated controller that never sends welcome, the failure is the welcome/auth deadline, not the liveness error, and stays retryable (`bootstrap_maybe_consumed` false). Red when the welcome read goes through the silence-converting reader. - New test `controller_silence_must_be_a_plausible_window` covers the validate bounds. - `cargo test -p paperclip-runner-core --lib -- durable::` passes (133 tests) on `af3c9b3649`, after merging `origin/master`; all runner-core test targets compile. - `cargo clippy` reports no new findings in the changed files. The one clippy error is in `runtime_notifications.rs` on master. - `pnpm verify` asks for broad CI coverage because Runner core changed. CI supplies it. ## Risks - A controller that does not ping (a server older than #19407) and stays idle for 90 seconds now gets a reconnect. The server reconnect loop handles this within its grace. - A server event loop blocked for more than 90 seconds can cause one reconnect. This is the same tradeoff the server side already makes. - No change to dial mode, to provider work, or to the work done before `turn.start`. - Previous-release story: no persisted run, session or lease state changes. `controller_silence` is an in-memory config field that `paperclip-runnerd` sets to the 90 s default, so a Runner resumed from state saved by the previous release behaves the same apart from the new liveness rule. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
11a0ff0205 |
feat(connections): per-company workload identity issuer with public signing keys (#22083)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use outside services through connections. The control plane holds each connection's credentials and makes the calls. > - Some clouds, such as AWS, do not need stored keys. They trust a signed token from an identity provider that they can verify against its public keys. > - Paperclip has no signing key whose public half it can publish. Agent identity keys are Ed25519, which AWS does not accept, and the agent's run receives the private key. Agent run tokens use a shared secret. > - This pull request gives each company its own signing key and publishes the public half as a standard OIDC issuer. > - The benefit is that a connection, such as the planned AWS connector, can get its own short-lived cloud credentials with no stored cloud keys. The connection's role in the customer's account sets its permissions. ## Linked Issues or Issue Description Refs #19414 and #10411. Those pull requests add OIDC *sign-in* to Paperclip. This pull request is the other direction: Paperclip *issues* tokens that outside clouds verify. **Subsystem affected** Connections (tool access) and the database. **Problem or motivation** An AWS connector should not store a long-lived AWS access key. AWS supports OIDC federation (`AssumeRoleWithWebIdentity`). AWS fetches the issuer's public keys over HTTPS and checks each token. Paperclip has no key that it can publish for this, so this method is not available. **Proposed solution** Each company gets an ES256 key that Paperclip creates on first use. The vault master key encrypts the private half. The issuer is `https://{instance}/oidc/companies/{companyId}`. Paperclip publishes a discovery document and a JWKS there. Tokens last 5 minutes and have `sub = connection:{id}`. Only the control plane signs them. The board can see key state and run planned rotation or emergency rotation. The design is in `doc/plans/2026-11-17-workload-identity-issuer.md`. The AWS connector plan that uses it is in `doc/plans/2026-11-17-aws-connector-and-minted-credentials.md`. **Alternatives considered** - Reuse agent identity keys. Rejected: AWS does not accept Ed25519, and the agent's run receives the private key. - Derive the key from the master key, with no table. Rejected: the master key alone would then sign as production. Worktree environments copy the master key on purpose. A master key rotation would also change the signing key and break every customer trust. - Use one issuer for the instance. Rejected: if a customer's role checks the issuer but not `sub`, any company on a shared instance could assume that role. ## What Changed - `packages/db`: new table `company_workload_identity_keys` and migration `0498`. The migration only creates a new table, so the previous release keeps working. Partial unique indexes allow one `active` key and one `next` key per company. - `server/src/services/workload-identity.ts`: lazy key creation with concurrent convergence, a private-key cache with a fail-closed key match check, the discovery document, the JWKS, `signConnectionToken`, and rotation steps. A key that is no longer active stays published for 24 hours. Paperclip calculates this when it reads the keys, so no background job is necessary. - `server/src/routes/workload-identity.ts`: public `GET /oidc/companies/{companyId}/.well-known/openid-configuration` and `GET /oidc/companies/{companyId}/jwks.json` (404 until a key exists). Board `GET /api/companies/{companyId}/workload-identity` and `POST .../workload-identity/rotation`, with an activity log entry for each rotation. - Token issuance writes a tool-access audit event. The event never contains the token. - `cli`: worktree seeds exclude the new table in the minimal mode and the full mode. This is the same as for `agent_identity_keys`, so a development copy never holds production's signing key. - Docs: `docs/api/workload-identity.md`, an entry in the API overview, and the two plan docs. - No connector uses `signConnectionToken` yet. The AWS connector pull request will use it. ## Verification - `cd server && npx vitest run src/__tests__/workload-identity.test.ts`: 8 tests pass. The tests cover these items: - The issuer requires https with no port and no loopback host. - The endpoints return 404 before a key exists. - Six concurrent first uses create one key. - The JWKS contains only `kty crv x y kid alg use`. - A token verifies against the published key and has the expected claims. - A company cannot sign for another company's connection, and its keys do not verify that company's tokens. - Signing stops when the public address is not usable or has changed. - Two-step rotation and emergency rotation work. - Board-only access is enforced, and each rotation writes an activity log entry. - Red/green: I put back a JWK that leaks `d` and removed the company check on the connection. Three tests failed. I restored the code, and all 8 tests passed. - `cd cli && npx vitest run src/__tests__/worktree.test.ts`: 63 tests pass. - `npx tsc --noEmit` passes for `packages/db`, `server` and `cli`. - I started this branch on a real dev server. Before a key existed, the public routes returned JSON 404 (not the UI page). After an emergency rotation from the board route, the JWKS returned one public P-256 key. On the http dev instance, discovery stayed 404 and the board route reported `not_https`. - `pnpm verify` exited 2 because of the migration. The required CI gates supply the broad coverage. - Not run: a real AWS `AssumeRoleWithWebIdentity` call. That needs a public HTTPS instance. It is the first step of the AWS connector work and will run against staging. ## Risks - The migration is low risk. It creates a new table with no backfill, and the compatibility checker classifies it as compatible with the running release. - The public routes are unauthenticated. They show only public keys, return 404 for companies without a key, and use random company UUIDs. Each request is one small indexed read. - The issuer URL shape is permanent after customers trust it. A change to the instance's public address breaks those trusts until the customer updates the identity provider. `signConnectionToken` stops on that mismatch when the caller supplies the recorded issuer. - Anyone who holds the production database and the master key could sign for that instance's companies. That is the same exposure as every other vault secret. - Edge routing on Paperclip Cloud must pass `/oidc/...` to the stack. I will confirm this on staging with the AWS connector work. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, web fetch of AWS documentation, a local dev server). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
43b2d8be22 |
feat(dashboard): add an experimental areas and responsibilities dashboard (#22069)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The dashboard is the first page a person sees in a company > - The classic dashboard shows agents, runs, costs and recent tasks > - It does not show what the person is responsible for, or if that work goes well > - People think in areas, such as Fundraising or Customers, and in the things they own in each area > - This pull request adds a dashboard built on areas and responsibilities, behind an experimental setting that is off by default > - The benefit is that a person sees what they own, how it is going, and what agents do for it, on one page ## Linked Issues or Issue Description No public issue exists for this work. The description follows the feature request template. **Subsystem affected** Dashboard, navigation, the task conversation, routines, and the instance experimental settings. **Problem or motivation** The classic dashboard counts agents and tasks. It does not say what a person owns or if it goes well. People who run a company with agents want to see their areas, the responsibilities in each area, the bar each one must meet, and the agents and routines that serve it. **Proposed solution** A person owns responsibilities. Each responsibility belongs to an area and has a bar, a number to reach. Projects, tasks and routines link to a responsibility, and the page shows its status from those links. An agent can interview the person and draft the dashboard. The person accepts or declines each change, and any change can be undone from a saved version. **Alternatives considered** Add the same data to the classic dashboard. That page is a fixed set of cards for company activity, so a second, person-centred page is clearer. The setting lets a person pick one of the two. **Roadmap alignment** This is an experimental feature behind `enableResponsibilities`. It is off by default and changes nothing for a person who leaves it off. ## What Changed - Add the setting "Areas & Responsibilities dashboard" (`enableResponsibilities`, off by default). On, Dashboard in the sidebar opens the new page, and the classic dashboard link is not shown in the sidebars or the command palette. Off, nothing changes. - Add tables and migrations 0492 to 0497 for areas, responsibilities, links to work, metrics, status reports, saved dashboard versions, and model-call records for summaries. - Add the API: areas, responsibilities, links, bars, metrics, status reports, summaries, runs, automation, and the dashboard conversation with versions and undo. Each route checks company access and writes to the activity log. - Add four task conversations with an agent: about a bar, about an automation, about a routine, and about the whole dashboard. The agent proposes a change. Nothing applies until a person accepts it. - Add standing checks: routines that an agent carries out on its heartbeat and reports. - Add the Dashboard page: search, counts, areas that open and close, a primary New area button, and a message box at the bottom of the page. Add the responsibility page with its bar, metrics, work and routines. - Add the Paperclip skill sections and runner API entries that let an agent use these routes. The runner skill inventory is regenerated (166 to 174 rows). - Keep the new runner API tests in their own file so `runner-api.test.ts` stays at 985 lines. - Onboarding is not changed. The onboarding changes that build on this work are a separate pull request. ## Verification - Type checks pass for `packages/db`, `packages/shared`, `server` (all layers) and `ui`. - `pnpm --filter @paperclipai/db check:migrations` passes. A new `drizzle-kit generate` run produces no further change. - Tests for every changed file pass: 26 server test files (3,009 tests), 116 UI test files (1,991 tests) and 28 shared test files (432 tests). - The runner capability inventory checks pass. - I started the app on a local database that already held earlier data. Master's new migrations and these migrations applied without error. With the setting on, the Dashboard and a responsibility page loaded with no console or server errors. The More menu and the command palette show one Dashboard. - I did not run `pnpm verify`, the full local suite, or the browser suites. Required CI covers them. - The agent conversations are tested with simulated agents. No real model has run them. ## Risks - Medium. The change is large, and the setting is off by default. With it off, the new routes refuse requests and the UI is unchanged. - Migrations only add tables and columns. Two replace a CHECK constraint, and one builds an index `CONCURRENTLY`. These two have the `online_compatible` override with a reason in the file, and the second one is listed in `MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS`. - Master can add migrations before this merges. The migrations then need new numbers. - `responsibilities.ts` (1,663 lines), `responsibility-summaries.ts` (1,239 lines) and one Storybook fixture file (1,305 lines) are new files over 1,000 lines. They each keep one cohesive unit together: the service for one table family, the model-call path for summaries, and the fixtures that the stories share. No existing file crosses 1,000 lines. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude: Claude Fable 5.2 (`claude-fable-5-2`) wrote most of the change, with Claude Sonnet 5.5 (`claude-sonnet-5-5`) for the final steps. Both used tool use, code execution and browser checks. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Scott Tong <scott@scottsmbpm5max.lan> Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com> |
||
|
|
4afcbfc0c7 |
fix(native): retry transient provider refusals while reattaching a handed-off run (#22118)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A release swap hands live native runs from the outgoing server to the incoming server. The incoming server reattaches each run to its original sandbox. > - Reattachment first resumes the exact sandbox lease through the sandbox provider plugin. > - In a release-swap wave, one reattach resume got an HTTP 502 from the provider gateway. The host did not retry it. The run failed with the generic `setup_failed` code after 13 minutes of agent work. > - The task then stayed blocked with a Retry banner for about 10 minutes, until the fresh-continuation fallback reached its bound and started a new run. > - This pull request retries a transient provider refusal during reattachment, with a bounded budget. It also reads the provider status from the plugin RPC error envelope, so the host sees the 502. > - The benefit is that a brief gateway failure during a swap is invisible to the user. The same run continues and no Retry banner shows. ## Linked Issues or Issue Description **What happened?** During a graceful release swap, the incoming server reattached a live native run to its retained sandbox. The `environmentResumeLease` plugin call failed with an HTML "502 Bad Gateway" body 280 ms after the reattach started. The other 18 handed-off runs in the same swap reattached in about 8 seconds. The host treated the 502 as an unknown error, so the run failed with `setup_failed`. The task stayed `blocked` with `canRetry: true` until the fresh-continuation fallback created a new run 10 minutes later. **Expected behavior** A transient provider refusal (HTTP 408/425/429/5xx, a connection errno, or a plugin RPC deadline) during reattachment is retried within a bounded budget. The same run continues hands-off. A definite refusal (for example HTTP 409) or a confirmed missing sandbox still fails at once with its own named reason. **Steps to reproduce** 1. Start a remote native run on a reusable sandbox. 2. Send SIGTERM to the server so it hands the run to the next server. 3. Make the first `environmentResumeLease` call on the incoming server fail with HTTP 502. 4. See that the run fails with `setup_failed` and the task shows Retry. **Paperclip version or commit** `master` at |
||
|
|
ea154ce55e |
Add bulk keyed issue document reads for native helpers (#22105)
## Thinking Path
> - Paperclip manages work for AI agents.
> - Native helpers read task documents through authorized API tools.
> - A scan of 146 cases needs one saved response and one download per
case.
> - The document service can read the same key across authorized tasks
with bounded queries.
> - This pull request adds a bounded bulk read with the existing task
access policy.
> - Helpers can transfer one batch and check current revisions before
fetching changed bodies.
## Linked Issues or Issue Description
**Subsystem affected**
Task document REST API, shared query contracts, and native API
discovery.
**Problem or motivation**
Per-task document reads make native sync scans cost hundreds of tool
calls. Task list timestamps do not prove that document content is
unchanged.
**Proposed solution**
Add `GET
/api/companies/{companyId}/issue-documents?key=notes&issueIds=...`. Read
up to 200 task UUIDs under current company and task permissions. Return
current bodies and revision metadata, or metadata alone with
`includeBody=false`.
**Alternatives considered**
Generic request batching would add tool execution and partial failure
rules. One bulk resource read removes the per-case relay cost with the
existing tools. Do not skip documents based only on task-row timestamps.
Keep managed skill files immutable; cleanup of copied skill test
fixtures belongs to those tests.
**Roadmap alignment**
This improves existing task documents and native API access. It adds no
new workflow or UI. The roadmap has no duplicate bulk document read
work. No duplicate open pull request was found.
## What Changed
- Add a bulk keyed document route and a company-scoped document reader.
Reuse the current batched task-read policy and completed-task read
receipts.
- Preserve request order and deduplicate IDs. Return `document: null`
for readable tasks without the key. Omit unreadable, hidden, foreign and
missing tasks without revealing which exist.
- Bound requests to 200 IDs and responses to 8 MiB of JSON bytes. Check
encoded body sizes in SQL before fetching bodies in the same read
snapshot. Build JSON within the byte budget. Oversized responses fail
with 413 and are never saved as partial artifacts.
- Admit at most two active reads per actor and eight per server
instance. Extra requests receive 429 with Retry-After. Keep the slot
until both the database work and response settle.
- Batch completed-handoff lookups and group child receipts by parent.
Extend the existing event batch writer for ordinary non-waking receipts
with atomic sequence allocation. Stored receipt shapes stay unchanged
for existing consumers.
- Expose revision-only reads without selecting document bodies. Document
native discovery, one save plus one download, and complete-inventory
checks.
- Add real HTTP, database and artifact tests for 146 open and completed
cases, 200 maximum-size bodies, metadata overhead, access failures,
query limits and JSON expansion. Cover admission limits, failure
cleanup, and concurrent event writers. Refresh the shared SDK source
pins.
## Verification
Final revision: `93dc8b029600211d79a050650f3dff82e5dad52f`.
- [CI run 44212220917, attempt
3](https://github.com/paperclipai/paperclip/actions/runs/44212220917)
passed. This includes typecheck, build, general tests, Runner checks,
serialized server suites, all e2e shards, and the final verify gate.
-
[Build](https://github.com/paperclipai/paperclip/actions/runs/44212220917/job/134506305267),
[e2e](https://github.com/paperclipai/paperclip/actions/runs/44212220917/job/134506309117),
and
[verify](https://github.com/paperclipai/paperclip/actions/runs/44212220917/job/134510062263)
are green.
- [Linux CI job
134506309291](https://github.com/paperclipai/paperclip/actions/runs/44212220917/job/134506309291)
passed all 16 bulk document integration tests. This includes the native
transfer of all 146 documents with the saved size and hash,
completed-case receipt batching, and size-only rejection of 200
maximum-size documents.
- [Greptile
review](https://github.com/paperclipai/paperclip/pull/22105#issuecomment-6965449032)
is 5/5 on the final revision. All review threads are resolved. Security
checks pass. GitHub reports CLEAN and MERGEABLE.
- Local server typecheck passed on macOS with Node 25.6.1. The focused
run below passed 177 tests; the Linux-only transfer test was skipped
locally and then passed in CI.
```sh
pnpm --filter @paperclipai/server typecheck
cd server
pnpm exec vitest run \
src/routes/issue-document-batch.test.ts \
src/services/native-runtime/issue-document-batch.integration.test.ts \
src/__tests__/documents-service.test.ts \
src/__tests__/openapi-routes.test.ts \
src/__tests__/heartbeat-run-event-atomic-append.test.ts \
src/__tests__/chat-completion-delivery.test.ts \
src/__tests__/native-child-task-read-routes.test.ts
```
- Shared typecheck and build passed. From `packages/shared/`, `pnpm exec
vitest run src/validators/issue.test.ts` passed 61 tests before the
rebase; the batch query contract did not change in the rebase.
- `node tests/runner-e2e/source-sdk-public-inputs.mjs <HEAD> --check`
passed. Runtime and lockfile pins are unchanged.
- `pnpm verify --explain` returned exit 2 because the API docs and
shared contracts require broader CI. The successful CI run above
supplies that coverage.
Failure and recovery record:
- Both performance findings reproduced before the fixes. Scale tests now
verify a size-only query for 200 large documents and one handoff lookup
plus two receipt-write statements for 146 completed cases. Concurrent
writers retain contiguous unique sequences and decoded payloads.
- Initial local runs found missing shared exports and OpenAPI route
coverage. These are fixed. Fixtures now respect Linux-only installation,
thrown cross-company denials, and the ES2022 TypeScript target. Rebase
conflicts preserved the onboarding coverage from master.
- CI attempt 1 interrupted Build, e2e shard 7 and six general-test
shards with runner shutdown signals. Attempt 2 recovered the tests but
its [Build
job](https://github.com/paperclipai/paperclip/actions/runs/44212220917/job/134499680425)
also received a shutdown signal and exited 143. No compiler or test
assertion failure was found in those interrupted job logs. The reason
the runners stopped remains unknown. Attempt 3 recovered Build and its
dependent verify gate on the same revision. Earlier interruptions are
not counted as passes.
## Risks
- Additive API only. No migration or existing endpoint response change.
- Helpers must adopt the batch response to gain the tool-call reduction.
They must verify that every requested task is present before treating
the scan as complete. Unreadable tasks are intentionally omitted.
- Split large document batches when the route returns 413. Metadata
remains available without bodies. Concurrency limits are per server
instance and can refuse simultaneous reads with 429; callers retry after
an active read finishes.
- This does not change company-owned helper inventory expiry or cleanup
tests, installed skill permissions, or generic tool batching. It does
not deploy to a tenant.
## Model Used
OpenAI `gpt-6.1-sol` through Codex in T3 Code, with xhigh reasoning,
tool use, and code execution. Context window size was not exposed.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
|
||
|
|
ce27dde855 |
Start onboarding in chat and defer execution until the user chooses work (#22077)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Onboarding connects an agent and gives the user a place to discuss work. > - The previous flow created an execution task and project before the user chose a scope. > - A standing chat can gather the goal and clear exit criteria first. > - This pull request opens chat after onboarding and starts a live welcome after the chat is visible. > - The agent proposes work for acceptance, or creates a task when the user explicitly requests one. > - Subscription setup and shared question state must work for this first conversation to succeed. ## Linked Issues or Issue Description **Subsystem affected** Company onboarding, agent chat, local subscription setup, task numbering, and shared interaction views. **Problem or motivation** The first session creates work before the user has agreed to a goal. Standing chats consume task numbers. An answered chat question can remain pending in the inbox. Claude code entry requires an extra click, and switching from Claude to Codex can leave an incompatible model selected. **Proposed solution** Open an owner-bound chat for every new company. Start a live welcome after the chat paints in a visible tab. Gather scope in conversation and use the existing task acceptance flow. Keep chat records out of the task number sequence. Publish question responses to shared caches and cancel stale reads. Submit pasted Claude codes once and wait for verified sign-in before connecting. **Alternatives considered** A fixed welcome would not use the onboarding context. A hidden execution task would still create work and consume a task number. Keep the existing task proposal and acceptance contract instead. **Roadmap alignment** This improves the shipped Agent Chat and Personal & Shared AI Accounts flows in ROADMAP.md. It does not add a separate execution or approval system. Related prior work: Refs #19643 and #19512. Related route handoff work: Refs #12557. This change replaces the automatic first task with chat; it also repairs the subscription and shared question state paths used during that journey. ## What Changed - Finish onboarding in agent chat for default and team-template companies. Create no execution task or project. - Queue one live welcome after visible chat content paints. Pass company goals and the initial idea as context. Preserve access, budget, and hiring controls. - Instruct the agent to gather a goal and exit criteria, offer an interview, and propose tasks for acceptance. Allow direct creation on an explicit user request. - Leave new standing chats unnumbered. The first execution task receives number 1. Preserve existing identifiers. - Synchronize answered question cards across chat and inbox, including concurrent requests and inactive cached views. - Submit a pasted Claude authorization code once. Show connection progress and hide the restart link while sign-in is still preparing. Detect rejected OAuth codes promptly. Clear incompatible models when the provider changes. - Use `Work with [agent name]` as the default chat composer placeholder. - Add regression coverage and update onboarding documentation and API notes. ## Verification - Completed a real Claude subscription journey on macOS with an isolated local database. Authorized the account, pasted the real code, and reached the review step without clicking Submit code or Connect. Get started opened chat and the live welcome run succeeded. The company had zero execution tasks, zero projects, and task counter 0. - On rebased commit c664949858, 6 browser cases passed for paste-to-connect-to-chat, task-free onboarding, existing-company routing, the native connection probe gate, desktop/mobile planning, and two-tab chat/inbox question synchronization. - On the rebased head, 419 focused UI tests passed. The focused server and adapter run passed 160 tests and hit one `socket hang up` in the existing authenticated chat route test. The full 72-test conversation suite passed on one repeat. The cause of that first socket failure remains unconfirmed; the passing repeat does not establish its cause. - UI typecheck and server declaration typecheck pass after the rebase. The first server check found a missing local dependency from master; a frozen-lockfile install repaired it. No dependency manifest or lockfile change was needed. - The first Greptile review found two welcome edge cases. Four new tests reproduced both before the fix. On commit b380f14ef9, all 114 onboarding and queue tests pass, including timeout retries and queued welcomes replaced by a user message or chat reset. Server source and focused test type checks pass on this revision. - [Greptile review](https://github.com/paperclipai/paperclip/pull/22077#issuecomment-6961533641) gives rebased commit |
||
|
|
9032f55d83 |
fix(ssh): support all Cloud SSH harnesses in remote task workspaces (#22078)
Support durable in-place SSH task workspaces across all declared SSH-capable
Cloud harnesses. Keep controller filesystem operations off remote paths,
preserve SSH session identity, and stage provider assets on their owning
execution target. Keep managed ACP conversation identity stable across
credential-home rotation and preserve Pi JSONL history after credential cleanup.
Verify with the real SSH heartbeat matrix, adapter and session regression
checks, and typechecking. Final CI passed on
|
||
|
|
323504e41e |
perf(runner): enable TCP_NODELAY for loopback PRP (#22091)
## Thinking Path > - Paperclip manages AI agents for work. > - Native Runner exchanges commands and events over WebSocket PRP. > - Both Runner connection modes use TCP sockets. > - Several small frames can follow each other during a start. > - Loopback peers can receive those frames promptly with TCP_NODELAY. ## Linked Issues or Issue Description **What existing behavior does this improve?** Delivery of PRP command results and events on local TCP connections. **Subsystem affected** Native Runner PRP transport. **Current behavior** Runner uses the default TCP setting for acknowledged small writes on its accepted and outbound PRP sockets. In an A/B test with a loopback model fixture, enabling TCP_NODELAY on the accepted Runner socket reduced median time to observe turn.started by 29 to 52 ms, depending on the provider and session state. **Proposed behavior** Enable TCP_NODELAY on accepted and outbound PRP sockets before the WebSocket handshake when the connected peer address is loopback. **Reason and benefit** The controller receives turn-start events sooner. The outbound path shares the same setup rule and has socket-option coverage. **Breaking changes** The change is a per-connection socket option. Existing launch arguments, durable checkpoints, and PRP frames carry forward. ## What Changed - Share initial stream configuration between the listener and dialer. - Check the actual peer address before enabling TCP_NODELAY. - Complete a real WebSocket handshake in one test for each connection mode and read back the option. ## Verification - `cargo fmt --manifest-path packages/paperclip-runner/runner/Cargo.toml --all --check` - `cargo test --offline --locked -p paperclip-runner-core --lib durable::transport::tests` passed locally on macOS (27 passed). - Both new tests failed on the original socket setup and passed with the change. - `cargo test --offline --locked -p paperclip-runner-core --lib --bins --test listener_accept` passed locally on macOS (676 passed, 4 ignored). ## Risks - TCP can send more small packets during high-volume local output. The check limits the option to loopback peers. The earlier A/B measured turn-start timing on the listener path. ## Model Used - OpenAI GPT-6 (Codex), with source inspection and local Rust tests. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g., `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge |
||
|
|
f295e496db |
fix(daytona): retry lease acquisition after a provider connection failure (#22087)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agent runs on Daytona start with a lease acquisition in the Daytona plugin > - When the host cannot reach Daytona, the Daytona SDK raises a connection error that has no HTTP status and no errno > - The host only retries a lease failure that carries structured evidence, so this failure became `setup_failed` and the task waited for a person to press Retry > - This pull request makes the plugin report the SDK connection error as a closed transport code that the host already retries > - The benefit is that a short network blip during sandbox startup no longer needs a Retry click ## Linked Issues or Issue Description **What happened?** In a restart-chaos wave (201 tasks, 6 graceful release swaps), the host could not resolve or reach Daytona for about 12 minutes. One task needed a Retry click. Its only run failed with `setup_failed` (`lease_acquire_failed`) and the message `Failed to acquire lease for environment "Daytona warm ..." (sandbox): read EADDRNOTAVAIL`. Automatic recovery did not continue the task because `setup_failed` is not a transient setup code. The task stayed failed for about 100 minutes until the grader pressed Retry. **Expected behavior** A lease acquisition that fails because the provider could not be reached is retried automatically with the bounded bootstrap budget, as `environment_provider_unavailable`. A person never needs to press Retry for a network blip. **Steps to reproduce** 1. Use the Daytona provider. 2. Make a Daytona API call during lease setup fail at the transport level (no HTTP response), for example with `read EADDRNOTAVAIL` or `getaddrinfo ENOTFOUND`. 3. See that the run fails with `setup_failed` and the task shows Retry. **Paperclip version or commit** master `ca34aca777` (wave) and `02ee538be9`. Root cause: the pinned `@daytonaio/sdk` converts an Axios transport error into `DaytonaConnectionError` (or `DaytonaConnectionTimeoutError`). It keeps neither the errno nor the cause. The worker RPC therefore sent no provider diagnostic, and `readTransientLeaseAcquisitionFailure` returned `null`. ## What Changed - The Daytona plugin wraps a `DaytonaConnectionError` from lease acquisition in an error with code `CONNECTION_FAILED`, and a `DaytonaConnectionTimeoutError` with code `ETIMEDOUT`. The message is unchanged. It reads the SDK class name only, never message text. - The plugin SDK closed diagnostic set accepts `CONNECTION_FAILED`, so the code crosses the worker RPC. - The host treats `CONNECTION_FAILED` as a transient connection failure. The run becomes `environment_provider_unavailable` and uses the existing bounded bootstrap retry (30 s, 60 s) and the automatic-run brake. - Refreshed `tests/runner-e2e/source-sdk-public-inputs.json` for the changed SDK file. ## Verification - Red/green: with the source change removed, the new plugin tests (`reports a DaytonaConnectionError during setup as a transient transport failure`, timeout variant) and the new host tests (`treats errno CONNECTION_FAILED as transient`, `retries a provider connection failure reported across the worker RPC`) fail. With the change, they pass. - `cd packages/plugins/sandbox-providers/daytona && npx vitest run` (637 passed). - `npx vitest run server/src/services/environment-provider-unavailable-error.test.ts packages/plugins/sdk/tests/environment-acquire-error.test.ts` (66 passed). - `pnpm typecheck` in the Daytona plugin passes. - `pnpm verify` asks for broad CI coverage because the SDK input registry changed. CI supplies that coverage. ## Risks - Low risk. A wrong Daytona API URL also produces `DaytonaConnectionError`. It now gets two bounded retries (about 90 s) before the same Retry state as before. - The retries count toward the automatic-run brake, so a long outage cannot multiply run starts across the company. - A create that timed out on the client keeps its existing creation-cleanup envelope. The retry is a new creation attempt with its own identity. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
eaf6461cee |
fix(server): give a slow remote more time to exclude agent files from Git (#22039)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Before a remote run starts, Paperclip runs a short Node program in the sandbox that keeps the reserved runtime directory out of task Git staging > - That program had one 15 second attempt. A freshly created sandbox is sometimes slow, so the attempt timed out > - The run then failed before any provider work started, with the generic `adapter_failed` code. Nothing retried it, and the wake that started the run was lost > - This pull request gives each attempt 30 seconds and retries a timed-out attempt, up to three attempts > - The benefit is that a slow sandbox no longer stops a task, while a real failure still fails at once and names its reason ## Linked Issues or Issue Description Builds on #21499 (merged), which adds the closed `reason=` code to this error. **What happened?** A run failed during preparation with "Could not exclude agent files from task Git staging". The sandbox lease was acquired about 50 seconds before the agent-file copy was registered (3 to 7 seconds on the same stack's earlier runs). The copy failed 20 seconds after it was registered, which matches the 15 second limit. Earlier failures with this message all took at least 16 seconds before failing, so they also match a timeout rather than an error from the program itself. **Steps to reproduce** 1. Start a remote run on a sandbox that takes more than 15 seconds to run a short command. 2. The run fails in the preparing stage and is not retried. **Expected behavior** A slow sandbox gets more time, and a timed-out attempt is retried. **Actual behavior** One 15 second attempt, then the run fails. ## What Changed - `agent-instruction-files.ts`: add `excludeRuntimeFromRemoteGit`. Each attempt gets 30 seconds. A timed-out attempt is retried, up to three attempts. Any other failure throws at once. The error keeps the closed `reason=` code from #21499. - `agent-directory-working-copies.ts` and `agent-instruction-working-copies.ts`: both remote call sites use the helper, so the private instruction copy also names a reason. - `execution-target.ts`: `runSshCommand` rejects a command its timeout killed with `code: null` and `killed: true`, but only `ETIMEDOUT` was treated as a timeout, so an SSH timeout was thrown instead of returned. A killed command now returns `timedOut: true`, as the sandbox path already does. - Tests: a timeout followed by success stages the agent files; three timeouts fail with `reason=timed_out`; a non-timeout failure is attempted once. An adapter-utils test covers the real SSH timeout rejection. ## Verification - `npx vitest run` on the agent-directory, instruction working-copy, Git exclusion, copy retry backoff, instruction-working-copy and remote checkpoint lock suites: 217/217 pass. - adapter-utils `execution-target` and sandbox suites: 173/173 pass. adapter-utils SSH suites: 65 pass, 2 skipped. Server adapter registry suite: 67/67 pass. - The new cases fail without this change. - `npx tsc --noEmit` passes for server and adapter-utils. ## Risks - Low. A sandbox that never answers now takes up to 90 seconds to fail instead of 15 seconds. - An SSH shell command that times out is now returned as `timedOut` instead of thrown. Every caller that checks the result already treats `timedOut` as a failure. The home-directory probe and the empty-file helper ignore the result, so for them an SSH timeout now behaves as a sandbox timeout already did. - The exclusion program is idempotent: it writes its file through a temporary name and a rename, so a retry after a late first attempt leaves the same result. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution in Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
f05b90508a |
refactor(core): remove retired compatibility paths (#22055)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Core manages chat authorization, AI connection defaults, navigation, and the plugin host. > - Core still writes old default rows and checks an Agent Chat flag that always reads true. > - It also carries a desktop rail that cannot open and private aliases with canonical equivalents. > - This pull request removes those paths and moves their tests onto the paths Core uses. > - The result is fewer Core database operations and less code to maintain. ## Linked Issues or Issue Description **What existing behavior does this improve?** Core AI default writes, Agent Chat execution and delivery, private plugin host and Runner setup, and board navigation. **Subsystem affected** Cross-cutting. Core server, board UI, private Runner helpers, and a repository guard script. **Current behavior** The server writes provider-scoped and per-method AI defaults, then reads only the provider-scoped rows. It reads settings to decide whether to block Agent Chat, although every settings view enables it. The desktop sidebar renders expanded while still tracking requests to open and close a retired icon rail. The agent client retries conflicts that the server already resolves when there is exactly one active match. **Proposed behavior** Write provider-scoped defaults directly. Use the existing Agent Chat authorization and retry checks without the redundant settings reads. Render the current sidebar directly and let the API report true agent reference conflicts. **Reason and benefit** A personal non-custom connection save or explicit default selection sends one fewer SQL statement. It also avoids the provider-default write that the legacy trigger performed when the old statement inserted or updated a row. A successful task-to-chat send or receipt replay avoids two transaction settings SELECTs when the singleton row already exists. Conversation comment, wake release, and retry paths also avoid a transaction settings read when they previously entered the gate. Savings in other settings paths depend on cache hits. Core-to-plugin RPC and plugin-to-Launcher HTTP traffic stay the same. **Breaking changes** The public plugin SDK, host navigation, and organization-switcher fields retain their existing interfaces and behavior. The settings API still accepts and reports the Agent Chat compatibility key. This change needs no schema migration or rollout ordering. **Additional context** Refs #10610 for prior reporting on the retired sidebar rail. Refs #21756 for adjacent Coordinator plugin slots, which remain a separate change. ## What Changed - Stop writing per-method AI defaults. Preserve the provider-scope upsert and first-account behavior. Keep the existing tables and migration trigger. - Remove Agent Chat checks that read a constant true value. Keep conversation ownership, task scope, session, and request-retry checks. - Remove unused lock-owner fields and private plugin lifecycle, secret extraction, Gmail connector, PRP setup, heartbeat resolver, and ACPX aliases. - Use a single API request for agent references. Remove retired sidebar rail state, hooks, and branches across the active and production snapshot layouts. Preserve desktop resizing, mobile drawer controls, contextual navigation, and public plugin slot inputs. - Remove unused FeedCard and AgentDetail inputs and the test-only Git push matcher alias. - Keep the cleanup that erases historical plaintext chat retries from browser storage. Production source in the touched files is 106,800 → 105,633 nonblank lines, down 1,167. The production Git diff adds 251 physical lines and removes 1,480, down 1,229. Those figures exclude tests, fixtures, docs, and Storybook. The entire Git diff adds 482 physical lines and removes 2,325, down 1,843. ## Verification - Merged master at `b56f240f45` into the PR branch as `f73fea4009`. The five sidebar files retain the expanded navigation cleanup and master’s explicit session-replay masking contract. The merge also preserves master’s account-repair recovery guard and GitHub star-prompt behavior. - Focused UI Vitest run passed 361 tests across 11 files. This covers analytics privacy and replay masking, sidebar and layout, GitHub star prompt, and agent detail. - Focused server Vitest run passed 45 tests across three files. This covers restored configuration handling, conversation recovery, and Agent Chat authority and receipt replay. - `pnpm --filter @paperclipai/ui typecheck`, the Git push guard and its 14 tests, and `git diff --check origin/master...HEAD` passed. - `pnpm verify --base origin/master` classified the Git-push guard as a global CI input and returned exit 2. GitHub CI supplied the broader coverage. - GitHub CI and Runner image checks passed on `f73fea4009`. Both required checks, `ci / verify` and `ci / e2e`, passed. [CI workflow](https://github.com/paperclipai/paperclip/actions/runs/44181261752) · [Runner image workflow](https://github.com/paperclipai/paperclip/actions/runs/44181261413) - Standard Greptile reported 5/5 with no actionable findings or open review threads. [Greptile review](https://github.com/paperclipai/paperclip/pull/22055#issuecomment-6959078925) - The optional Superagent Security Scan finished neutral with an inconclusive workflow result and zero annotations. The final rollup had 61 successes, five skips, and one neutral, with no failed or pending checks. [PR checks](https://github.com/paperclipai/paperclip/pull/22055/checks) ## Risks Agent Chat authorization and retry are sensitive to small query changes. The final diff keeps the conversation agent field and all existing authorization and idempotency checks. The tests cover revoked defaults, legacy migration reads, bound-listener authority, and mobile and desktop navigation. Installations that still run software old enough to read the per-method AI table will no longer see new defaults in that table. Current Core reads the provider-scoped table. ## Model Used OpenAI Codex, GPT-6.1 Sol (`gpt-6.1-sol`), with source inspection and shell-based tests. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
23ce68a8dc |
feat(connections): end Google access when a Paperclip-managed Google connection is removed (#22065)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Connectors let agents use Google Workspace through a Google sign-in
that Paperclip Cloud manages for the user
> - When a user removes a Paperclip-managed Google connection, Paperclip
deletes the tokens locally, but the grant stays live at Google
> - Google's OAuth review expects that a disconnect ends the app's
access, and users expect it too
> - Google's revoke ends the user's whole grant to the shared client, so
only the Paperclip Cloud broker can decide when it is safe to revoke
> - This pull request asks the broker to revoke each removed grant,
keeps local removal unconditional, and tells the user the outcome in
plain language
> - The benefit is that removal ends Google access when no other
Paperclip connection needs it, and the user knows what to do when it did
not
## Linked Issues or Issue Description
**Subsystem affected**
Connectors: Paperclip-managed Google Workspace and the legacy
per-service Google connections (server removal, shared contracts,
connection UI).
**Problem or motivation**
Removing a Paperclip-managed Google connection or grant was local only.
The refresh token was deleted in Paperclip, but Google still listed
Paperclip as having access to the account. The docs said so ("Removal is
local for managed grants").
**Proposed solution**
On removal, send each removed grant's refresh token to the broker's
signed `POST /v1/connector/revoke`. The broker revokes at Google only
when no other live binding could share the grant. Paperclip records the
broker's outcome code and shows one of three plain messages. Local
removal never waits on, or fails because of, that call.
**Alternatives considered**
Call Google's revoke endpoint from the app. This ends the user's whole
grant to the shared client and can break their other Google connections,
so the broker owns the decision.
**Additional context**
Older brokers answer 409 `REVOCATION_NOT_AVAILABLE`. The app treats
that, a timeout, and a network error as "could not end access at Google"
and still removes the connection.
## What Changed
- `paperclip-cloud-connector.ts`: `revoke()` takes an optional
`timeoutMs`, returns the broker's `outcome` from an allowlist, and keeps
`REVOCATION_NOT_AVAILABLE` as an allowed rejection reason.
- New `tool-access/connections/google-access-removal.ts`. For a managed
Google connection, `prepare()` reads each removed grant's refresh token
and returns a `send()` step. `send()` calls the broker for each distinct
token, one after another, under one 5-second deadline. Every result and
every error (including a Paperclip Cloud client that cannot be created)
becomes an outcome code. It never rejects and never logs a token. An
unexpected error is logged with the error name only and reported as
`unexpected_error`.
- Order for removing a whole connection: read the tokens, run the whole
local teardown (grants, installs, app profile, gateway tokens, runtime
slots, catalog, OAuth state, archive the connection), call the broker,
delete the sent refresh-token secrets whatever the outcome, then delete
the remaining secrets. A failure anywhere in the teardown makes no
broker call. Order for removing one grant: read the token, commit the
revocation, call the broker, delete the grant's refresh-token secret.
`send()` owns the call and the deletion through an injected
secret-removal function.
- Owed revocations: a revoked managed Google grant whose refresh-token
secret still exists (and that nothing live uses) is sent by every later
removal, then the secret is deleted. This covers a process stop after
the teardown and before the call, with no new column. Once the secret is
deleted, nothing is sent again.
- Shared tokens: the shared (organization) sign-in writes the same
secret refs to the organization grant and the connection. So revoking an
organization grant alone neither calls the broker nor deletes the
secret, because the connection still uses that token; removing the
connection does both. The same rule applies to any refresh token still
used by another live grant or connection.
- Audit history: once the broker call settles, a
`connection.google_access_removal` audit event records `reasonCode` =
result and `providerAccess` (plus `grantId` for a single grant). If that
write fails, the removal still succeeds and the failure is logged.
- Revoke signs with the subject that consented to the grant
(`providerTenant.externalId`, saved by the managed callback from the
claim). Grants saved without it fall back to the refresh rule. Refresh
is unchanged; see Risks.
- `removal.ts` and `grants.ts`: `providerAccess: { provider, result,
outcomes }` goes to the responses and to the `tool_connection.archived`
and `tool_connection.grant_revoked` activity entries. The tool access
audit field `providerRevocation` keeps its Vercel meaning only.
- `packages/shared`: `ManagedGoogleAccessRemoval`,
`ManagedGoogleRevocationOutcome`, `ConnectionGrantRevocationResult`.
- UI: one helper, `connectionRemovalToast`, builds the removal toast
(base sentence plus the Google notice, tone and action) for Connectors,
Connections and the app page. No codes are shown.
- API: `docs/api/tool-connections.md` documents both DELETE responses
and `providerAccess`. The OpenAPI registration describes the optional
field and its four results.
- Docs: `GOOGLE-WORKSPACE.md` (order, owed revocations, decision table),
`GMAIL.md`, the Google connector memory note, and the help page on
deleting connection data.
Decision table, judged over the distinct tokens sent in this removal:
| Outcomes | `result` | User message |
| --- | --- | --- |
| Every token `revoked` | `ended` | "Paperclip's access to this Google
account was also ended at Google." |
| Any failure-type code: `provider_revocation_failed`,
`binding_not_known` (the broker had no record, so Google was not
called), `provider_revocation_disabled`, `revocation_in_progress`,
`revocation_not_available`, `broker_unavailable`, `broker_error`,
`credential_unavailable`, `unexpected_error` | `not_ended` | "Paperclip
removed the connection but couldn't end its access at Google. You can
remove Paperclip from your Google account's third-party connections." +
"Open Google account connections" |
| Only `other_connections_remain` | `other_connections_remain` | "Other
Paperclip connections still use this Google account, so Google keeps
Paperclip's access until you remove those too." |
| At least one `revoked`, the rest `other_connections_remain` |
`ended_unconfirmed` | "Paperclip's access was ended at Google. If more
than one Google account was connected here, check your Google account's
third-party connections to be sure." + "Open Google account connections"
|
Grants record no Google account identity: the managed callback saves
`externalId` (the Paperclip subject), `name` (the provider name), and
OAuth timing and scopes, and none of the 14 scopes returns an account
identifier. So the last row is always `ended_unconfirmed`. This includes
two tokens of one user and several agent grants on one Google account.
## Verification
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/google-managed-connection-removal.test.ts
src/services/tool-access
src/services/paperclip-cloud-connector-revoke.test.ts
src/services/paperclip-cloud-connector.test.ts
src/__tests__/tool-connection-removal.test.ts
src/__tests__/tool-access-service.test.ts
src/__tests__/openapi-routes.test.ts` (714 passed)
- `pnpm --filter @paperclipai/ui exec vitest run
src/features/connections/googleAccessRemoval.test.ts src/pages/apps`
(passed)
- Server test typecheck (`node server/scripts/typecheck-layers.mjs`)
passes.
- Red then green: the server tests failed on `master` sources (21), then
each review round's new tests failed on the previous head and pass now.
They cover: the order on both paths, local failure before the grant
commit making no call and the retry sending, cleanup failure after the
call making no second call, a process stop between commit and call being
sent on retry with the secret deleted after, a Paperclip Cloud client
that cannot be created, the consenting subject for an organization
grant, sequential sends under one deadline, each row of the decision
table (per-agent and same-user cases give `ended_unconfirmed`, a mixed
failure gives `not_ended`), the unexpected-error log without a token, no
token in any log call, the delete-stored-data option, and a toast test
per surface.
- Added time, measured locally with a stubbed broker that answers at
once: median 22.1 ms against 20.3 ms without the broker step (12 runs
each), about 2 ms. With a real broker, one round trip per removed token,
capped at 5 seconds in total.
- `pnpm verify` exits 2 (a global CI input changed), so required CI
supplies the broad coverage.
- Not verified against a live broker or a real Google account.
## Risks
- A removal of a managed Google connection or grant can take up to 5
seconds longer when the broker is slow.
- Refresh subject is not changed in this PR. In the broker
(`recordProviderGrant`), a ledger row's subject is fixed when the row is
first written, and a refresh under another subject leaves that row
untouched. So moving refresh to a new subject could stop updating the
row's last-seen time. After 200 days the row would then count as not
live, and a later removal elsewhere could revoke at Google while this
connection still works. That risk cannot be ruled out from code for rows
written before this release, so both refresh paths keep their old rules.
The two refresh paths already use different subject orders today: the
gateway prefers `connectorSubjectAgentId` and then
`connectorSubjectUserId`, while background refresh prefers the grant's
own subject. That is pre-existing, and this PR leaves it unchanged.
Revoke uses the consenting subject, which matches the claim-time ledger
row. When the row was first written by a refresh under a different
subject, the broker answers `binding_not_known` and the user gets the
warning.
- Repeated removals can send an already-removed token again; the broker
returns its recorded outcome and changes nothing at Google.
- Against an older broker, users see the "could not end access at
Google" message, which is accurate.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code execution.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
24728076d6 |
build(deps-dev): bump wrangler from 4.156.2 to 4.158.0 in /scripts/typecheck-sandbox-providers (#20200)
Bumps [wrangler](https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler) from 4.156.2 to 4.158.0. <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/cloudflare/workers-sdk/releases">wrangler's releases</a>.</em></p> <blockquote> <h2>wrangler@4.158.0</h2> <h3>Minor Changes</h3> <ul> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16186">#16186</a> <a href="https://github.com/cloudflare/workers-sdk/commit/f1d81a20c8e535ec7cb870143283f4a683fec70d"><code>f1d81a2</code></a> Thanks <a href="https://github.com/leostera"><code>@leostera</code></a>! - Support local Artifacts across Wrangler, Vite, and Workers Vitest</p> <p>Set <code>remote: false</code> on an Artifacts binding to opt into the Miniflare simulator and persistent local repositories during development. Omitted <code>remote</code> continues to use the deployed resource, with a warning that changes affect real repositories; <code>remote: true</code> explicitly selects it. When remote bindings are disabled (<code>wrangler dev --local</code>, or Vite's <code>remoteBindings: false</code>), Artifacts bindings use the local simulator. Workers Vitest uses the local simulator when <code>remote</code> is omitted, so tests do not change real repositories by accident; set <code>remote: true</code> to test against the deployed resource. Local development does not require Cloudflare credentials, but does require Git 2.32 or newer on the host.</p> <p>In Miniflare's own options, Artifacts bindings route like every other binding: only <code>dev.remote: true</code> with a remote proxy connection uses the deployed resource. Wrangler and Vite resolve the deployed-by-default rule, and Workers Vitest its local default, before passing options to Miniflare.</p> </li> </ul> <h3>Patch Changes</h3> <ul> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16700">#16700</a> <a href="https://github.com/cloudflare/workers-sdk/commit/dc35efbd3cdfe67b3ef972c75b8faae65dfed195"><code>dc35efb</code></a> Thanks <a href="https://github.com/cjol"><code>@cjol</code></a>! - Bump bundled <code>brace-expansion</code> to pick up security fixes</p> <p>These packages bundle <code>brace-expansion</code> (a dependency of <code>minimatch</code>), and the bundled versions were affected by published advisories. The bundles now include <code>brace-expansion</code> 2.1.7 (from 2.0.1) and 5.0.12 (from 5.0.5). Normal glob patterns expand as before; only the pathological patterns targeted by the advisories are handled differently.</p> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16700">#16700</a> <a href="https://github.com/cloudflare/workers-sdk/commit/dc35efbd3cdfe67b3ef972c75b8faae65dfed195"><code>dc35efb</code></a> Thanks <a href="https://github.com/cjol"><code>@cjol</code></a>! - Bump bundled <code>fast-xml-parser</code> from 4.4.1 to 4.5.5 to pick up security fixes</p> <p>Miniflare bundles <code>fast-xml-parser</code> into its local R2 S3 API, and Wrangler bundles it through the AWS SDK used by <code>wrangler pipelines</code>. Version 4.4.1 is affected by several published advisories, and 4.5.5 includes their fixes. XML handling does not change.</p> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16700">#16700</a> <a href="https://github.com/cloudflare/workers-sdk/commit/dc35efbd3cdfe67b3ef972c75b8faae65dfed195"><code>dc35efb</code></a> Thanks <a href="https://github.com/cjol"><code>@cjol</code></a>! - Bump bundled <code>minimatch</code> from 5.1.6 to 5.1.9 to pick up security fixes</p> <p>These packages bundle <code>minimatch</code>, and 5.1.6 is affected by published ReDoS advisories. Version 5.1.9 includes the fixes. 5.1.8 is skipped because it broke recursive <code>**</code> matching, which D1's <code>migrations_pattern</code> relies on.</p> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16700">#16700</a> <a href="https://github.com/cloudflare/workers-sdk/commit/dc35efbd3cdfe67b3ef972c75b8faae65dfed195"><code>dc35efb</code></a> Thanks <a href="https://github.com/cjol"><code>@cjol</code></a>! - Bump bundled <code>shell-quote</code> from 1.10.0 to 1.11.0 to pick up a security fix</p> <p><code>shell-quote</code> is bundled into Wrangler, which uses it to parse and quote shell commands such as custom build and Pages dev commands. Version 1.10.0 is affected by a published advisory, and 1.11.0 includes the fix. Command parsing does not change.</p> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16700">#16700</a> <a href="https://github.com/cloudflare/workers-sdk/commit/dc35efbd3cdfe67b3ef972c75b8faae65dfed195"><code>dc35efb</code></a> Thanks <a href="https://github.com/cjol"><code>@cjol</code></a>! - Bump bundled <code>yaml</code> from 2.8.1 to 2.9.0 to pick up a security fix</p> <p><code>yaml</code> is bundled into Wrangler, which uses it to show container application details. Version 2.8.1 is affected by a published advisory, and versions from 2.8.3 onwards include the fix. Output does not change.</p> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16688">#16688</a> <a href="https://github.com/cloudflare/workers-sdk/commit/fa3edb325694670084bc38af02232957315ccdb5"><code>fa3edb3</code></a> Thanks <a href="https://github.com/FlorentCollin"><code>@FlorentCollin</code></a>! - Use the <code>account_id</code> from the configuration file in <code>wrangler d1 migrations list --remote</code></p> <p>Before this change, the command ignored the <code>account_id</code> in the configuration file. When your login had access to more than one account, the command failed in non-interactive mode. In interactive mode, it asked you to select an account. The command now uses the configured <code>account_id</code>, as <code>wrangler d1 migrations apply</code> does.</p> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16695">#16695</a> <a href="https://github.com/cloudflare/workers-sdk/commit/b2061f40f812d8888b461f68506552b58f8e468b"><code>b2061f4</code></a> Thanks <a href="https://github.com/apps/dependabot"><code>@dependabot</code></a>! - Update <code>DEFAULT_COMPAT_DATE</code> to 2026-11-04</p> <p>Use the bundled workerd release's compatibility date by default when scaffolding new projects or when no compatibility date is configured.</p> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16695">#16695</a> <a href="https://github.com/cloudflare/workers-sdk/commit/b2061f40f812d8888b461f68506552b58f8e468b"><code>b2061f4</code></a> Thanks <a href="https://github.com/apps/dependabot"><code>@dependabot</code></a>! - Update dependencies of "miniflare", "wrangler"</p> <p>The following dependency versions have been updated:</p> <table> <thead> <tr> <th>Dependency</th> <th>From</th> <th>To</th> </tr> </thead> <tbody> <tr> <td><code>@cloudflare/workers-types</code></td> <td>^5.20261103.1</td> <td>^5.20261104.1</td> </tr> <tr> <td>workerd</td> <td>1.20261103.1</td> <td>1.20261104.1</td> </tr> </tbody> </table> </li> <li> <p><a href="https://redirect.github.com/cloudflare/workers-sdk/pull/16306">#16306</a> <a href="https://github.com/cloudflare/workers-sdk/commit/36e64f20025cf0bd5e99a585ca3427c8d75fd18b"><code>36e64f2</code></a> Thanks <a href="https://github.com/efalcao"><code>@efalcao</code></a>! - Report Cloudflare Access login redirects on remote bindings instead of looping until "Too many redirects"</p> </li> </ul> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/cloudflare/workers-sdk/commit/c579d500d0c5732393f2e85f0cdd085167aee32e"><code>c579d50</code></a> Version Packages (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16681">#16681</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/f1d81a20c8e535ec7cb870143283f4a683fec70d"><code>f1d81a2</code></a> [miniflare] Enable local Artifacts in development tools [3/3] (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16186">#16186</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/dc35efbd3cdfe67b3ef972c75b8faae65dfed195"><code>dc35efb</code></a> Bump dependencies to clear 101 Dependabot alerts (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16700">#16700</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/4d88a45a952542c55ec63bbca671fb1f003a09c7"><code>4d88a45</code></a> [miniflare] Stabilize Artifacts integration tests on Windows (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16693">#16693</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/0083f807de557d771f9d2d4f08d6406f5062c295"><code>0083f80</code></a> [wrangler] Harden the local KV pagination regression test (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16697">#16697</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/fa3edb325694670084bc38af02232957315ccdb5"><code>fa3edb3</code></a> [wrangler] Use config account_id in d1 migrations list --remote (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16688">#16688</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/9a0732c3f4f6cbbc016a7134fc1d20edb98b454e"><code>9a0732c</code></a> Version Packages (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16654">#16654</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/44d1ee439c0a077f2fed4d86e35a4edf46b51f74"><code>44d1ee4</code></a> fix(wrangler): stop <code>wrangler delete</code> orphaning Container applications (<a href="https://github.com/cloudflare/workers-sdk/tree/HEAD/packages/wrangler/issues/16011">#16011</a>)</li> <li><a href="https://github.com/cloudflare/workers-sdk/commit/8ac43df32667a77cd7e8e267da86e96645e3031b"><code>8ac43df</code></a> Require explicit route metadata flags when downloading Worker configuration (...</li> <li>See full diff in <a href="https://github.com/cloudflare/workers-sdk/commits/wrangler@4.158.0/packages/wrangler">compare view</a></li> </ul> </details> <br /> [](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) </details> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> |
||
|
|
73dc33c620 |
fix(runner): keep a disk reserve so a full sandbox disk does not strand the runner (#22068)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents in a Paperclip-managed sandbox run under the Paperclip runner (`runnerd`), which keeps durable state on the sandbox disk > - An agent can fill that disk with its own work. In one case the agent installed a Rust toolchain and a second checkout with dependencies on a 10 GiB sandbox > - `runnerd` then could not write its state and exited. Each relaunch tried to upload its launch files to the full disk and failed, 83 times in 7 minutes > - The run ended as a generic provider failure that asked a person to inspect it, and Retry repeated the same failure > - This pull request keeps a small disk reserve that belongs to Paperclip. Recovery releases it to relaunch the runner, and stops at once with a named code when nothing is left to free > - The benefit is that the agent's turn can continue and see the full disk in its own tool output, instead of the run dying with it ## Linked Issues or Issue Description **What happened?** An agent in a managed Daytona sandbox filled the 10 GiB disk. `runnerd` exited with `failed to persist bounded diagnostic: No space left on device (os error 28)`. Runner process recovery then retried for the full 420000 ms reconnect grace. Every attempt failed with `.paperclip-upload-<id>.tar.gz: create: ... no space left on device`. The run failed as `native_provider_terminal_failed`, and the recovery asked a board user to verify that the provider stopped. **Steps to reproduce** 1. Run an agent in a managed sandbox and have it fill the disk (for example a Rust toolchain plus a full dependency install). 2. `runnerd` exits when it next writes its state. 3. Watch recovery retry the relaunch upload until the grace expires. **Expected behavior** Paperclip relaunches its runner on a disk the agent filled, so the turn continues and the agent sees the full disk in its tools. When the runner truly cannot start, recovery says so at once with a named cause instead of retrying for 7 minutes. **Environment** Managed Daytona sandbox (fleet snapshot, 4 CPU, 8 GiB memory, 10 GiB disk), `paperclip_runner` native runtime. ## What Changed - New `server/src/services/native-runtime/remote-runner-disk-reserve.ts` owns the reserve: hold/release scripts, the full-disk classifier, and `createRemoteRunnerDiskReserve`. A release waits for an in-flight hold, and no hold starts after a release. - Both remote runner launchers (agent runs and Dot) get a reserve path in managed sandboxes only: `<workspace>/.paperclip-runtime/paperclip-runner/disk-reserve`. Workspace saves and Git already exclude `.paperclip-runtime`. SSH hosts get no reserve. - After the first launch's identity is confirmed, the launcher holds 256 MiB in the background, only while 2 GiB more is free. It is off the startup path. - A relaunch releases the reserve before it stages. A launch that hits a full disk while staging releases the reserve and stages once more. - Release tries twice and reports `released`, `not_held` or `failed`. Only `not_held` ends the launch with `sandbox_disk_full`. A release that cannot run rethrows the original error, so recovery still retries. - Command-based staging (no `syncIn`) keeps a full disk recognizable with an `ENOSPC` code instead of a bare `runner_remote_*_staging_failed`. - `SANDBOX_DISK_FULL_FAILURE_CODE` and `isSandboxDiskFullFailure` live in the runner package. Runner process recovery checks the error code and stops at once instead of retrying for the whole grace. Other staging failures still retry. ## Verification - Red before the fix, green after: - `server/src/services/native-runtime/remote-runner-disk-reserve.test.ts`: release-and-restage, release before relaunch, `sandbox_disk_full` when release frees too little, no retry for a failure that is not a full disk, hold/release scripts in a real shell, no hold below the free-space floor. Before the fix, the launch rejected with the exact upload error from the incident. - `packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts` "fails at once when a replacement cannot be staged because the sandbox disk is full": before the fix it was still retrying after 4 s; after, it fails with `sandbox_disk_full` after one replacement. - Kept: "retries a replacement whose staging failed before any process launched" still passes, so a raw transient staging failure still retries. - Updated: "confirms no replacement process exists when staging fails before the launch RPC" now expects `sandbox_disk_full` with the upload error as cause. Exit is still confirmed and no launch RPC runs. - Real sandbox from the same fleet snapshot (Daytona, 10 GiB): hold created a 256 MiB reserve. The disk was filled to 100%. A 5 MB write then failed. Release returned `true`, and a 50 MB write then succeeded. A second release returned `false`. Hold on the now 98% full disk did not create a reserve. - `pnpm --filter @paperclipai/server exec tsc --noEmit` passes. `pnpm verify` result is in a comment below. - Review round: tests for a lost release RPC, hold/release ordering, command-based staging on a full disk, the hold after a dispatched first launch (not on relaunch), and no reserve on SSH. Each launcher-level test failed with its fix removed. - Focused suites on the review revision: transport 335/335, launcher 130/130 (filtered), launch assets 35/35, reserve 14/14. Server and runner typecheck pass. - Not run: a full product run in which an agent fills the disk and the relaunched `runnerd` resumes the turn end to end. ## Risks - Each managed sandbox holds 256 MiB more disk while it has more than 2 GiB free. That is 2.5% of a 10 GiB sandbox. - A relaunch for any reason releases the reserve for the rest of that run. The next run's launch takes it again. - If the agent keeps writing after the relaunch, the disk can fill again. The second time, nothing is left to release, and the run fails at once with `sandbox_disk_full` instead of after 7 minutes. - The run's error code is still `native_provider_terminal_failed`. The message now names `sandbox_disk_full`. A dedicated failure code and recovery text are a follow-up. - `runnerd` loses its own error message when it cannot persist its diagnostic. This PR does not change the Rust binary. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
3a41e54c51 |
perf(runner): start ACPX once on parked checkpoint relaunch (#22064)
## Thinking Path > - Paperclip manages work for AI agents. > - Runner uses ACPX to resume provider sessions from durable checkpoints. > - A parked Runner can be gone after a reboot or retention eviction. The host can then verify the saved park checkpoint and start a replacement process. > - The relaunch currently opens a sidecar for source-run readiness and opens another for the incoming run. > - The replacement Runner keeps the source-run command fence until authenticated attachment. > - Runner can open the sidecar once with the incoming run's bindings and verify dormancy before it accepts the attachment. ## Linked Issues or Issue Description Refs #19912 for ACPX run and tool authority design. **What existing behavior does this improve?** ACPX follow-up when the parked Runner process is gone and the host starts a replacement from its verified park checkpoint. **Subsystem affected** Native Runner hosting and the ACPX provider executor. **Current behavior** The readiness probe and the idle event poll both enter generic recovery. Recovery opens the source-run sidecar. Attachment then closes it and opens a new sidecar for the incoming run. **Proposed behavior** A host can signal this path through private Runner control after verifying an earlier ACPX park checkpoint and confirming that the old execution has stopped. The replacement Runner checks provider eligibility and checkpoint settlement, serves readiness from saved state, and fences commands until authenticated `run.attach` starts the provider with the incoming run’s bindings. A live frozen Runner follows the existing thaw and claim flow. **Reason and benefit** This removes a sidecar startup and shutdown from the time to the next ACPX turn while preserving the conversation and applying the incoming run’s tool, instruction, and workspace bindings. **Breaking changes** The launch argument is optional and requires private host control in listener mode. The feature reads checkpoints from the previous release. No checkpoint or controller message format changes. ## What Changed - Keep a relaunched park within the existing host claim command fence. - Load a settled provider checkpoint that qualifies for host parking without opening the provider during readiness or polling. - Open the provider with the incoming run's settings. Verify the session identity and that it has no active work before publishing the new provider checkpoint. - Verify one sidecar start, preservation of the saved checkpoint on failed admission, and rejection of early turn execution. ## Verification - `cargo fmt --manifest-path packages/paperclip-runner/runner/Cargo.toml --all --check` - `cargo test --offline --locked -p paperclip-runner-core --lib --bins` passed locally (673 passed, 4 ignored). - The confined sidecar regression uses previous-release checkpoints for two ACPX providers. It verifies a single start on attachment for both and preserves the saved checkpoint when the live provider reports an active goal. - The authenticated loopback test restarts with a saved incoming provider checkpoint and a prepared authority receipt. It verifies receipt replay, rejection of the prior authority after activation, and command execution under the incoming run. - `cargo test --offline --locked -p paperclip-runner-core --test acpx_warm_attachment --test acpx_park_readiness --test durable_recovery` passed locally (19 passed). - Hosted CI passed. Greptile scored the current commit 5/5 with no unresolved review threads. ## Risks - An incorrect checkpoint could cross a run boundary. The private host signal requires settled Runner and ACPX provider checkpoints. Runner verifies live session identity and dormancy before transferring authority. - The existing transition receipt handles reconnects after attachment. The optional launch signal has no effect on older Runner binaries. ## Model Used - OpenAI GPT-6 (Codex), with source analysis and local Rust process and protocol tests. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have documented the private launch contract and compatibility above - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge |
||
|
|
84b75502c0 |
fix(ssh): support ACP with durable Cloud workspaces (#22063)
## Thinking Path > - Paperclip coordinates agents that run on local and remote computers. > - SSH environments use the harness installed on a computer the operator controls. > - Cloud SSH tasks now use durable remote workspaces. > - Claude and Codex default to ACP, but ACP rejects those in-place SSH workspaces. > - The shared ACP engine already has SSH process bridges and managed account delivery. > - This pull request lets that engine use the remote task directory and stage runtime assets separately. > - The benefit is ACP execution with the selected Paperclip account and the existing SSH environment. ## Linked Issues or Issue Description **What happened?** A Claude or Codex agent using the default ACP engine cannot run in a volume-free Cloud SSH environment. The adapter rejects its in-place workspace before execution. Setting the engine to CLI works around that restriction. **Expected behavior** ACP runs directly in the authoritative remote task directory. Paperclip keeps using the selected account, permission settings, process bridges, and durable workspace owner. **Steps to reproduce** 1. Create an SSH environment with agent-managed authentication on a volume-free server. 2. Select a Paperclip AI account for a Claude or Codex agent and leave its engine at the default. 3. Assign a task to the agent. 4. Observe the ACP in-place workspace rejection. Related: #21957 adds durable Cloud SSH workspaces. #21248 adds agent-selected SSH accounts. A search for SSH ACP work found #21248 and no open duplicate. ROADMAP.md has no overlapping item. ## What Changed - Admit managed SSH ACP with an in-place workspace in both adapters. - Keep ACP's session directory and fingerprint bound to the remote task directory. - Stage private runtime assets with workspace copying disabled. The remote workspace owner still saves task files. - Retain the copy-mode SSH path and existing account, confinement, and command availability checks. No engine fallback or permission change is added. - Extend the existing lifecycle tests for in-place staging, session reuse, current credentials, account changes, and cleanup after bridge or turn failures. - Extend the real OpenSSH/Postgres heartbeat test to the default ACP engine. Its protocol fixture creates a file and verifies conversation history on a follow-up. - Update the SSH setup documentation. Workspace placement belongs to the shared ACP engine. The adapter changes remove their explicit SSH admission refusals. The server test exercises the existing heartbeat path; no server execution logic changes. Existing large test files retain their shared harnesses instead of adding a second lifecycle mock graph. ## Verification - 418 focused tests pass across 7 suites: 411 adapter/ACP lifecycle tests, all 4 real SSH workspace tests, and 3 real ACP host-spawn smoke tests. - Typechecks pass for adapter-utils, Claude, Codex, and the server. - `pnpm verify` returns 2 because this touches shared runtime code and deployment documentation. Required CI supplies the broader build, browser, and release coverage. - Tested head: `33b17a9a21c0a5929523702ebed9c8faa3b22955`. - `git diff --check` and the local secret/PII scan pass. Greptile reviewed the tested head at 5/5 with no actionable findings. Final-head [CI attempt 2](https://github.com/paperclipai/paperclip/actions/runs/44167483231/attempts/2) passes on `33b17a9a21c0a5929523702ebed9c8faa3b22955`: 58 checks pass and 6 are skipped, with no failures or pending checks. Both required gates pass. Four first-attempt jobs were cancelled after their runners received shutdown signals, confirmed in each job log; automatic recovery reran those jobs successfully. No source change was needed for that recovery. Greptile is 5/5 with no unresolved findings, and the branch has no merge conflicts. GitHub still requires code-owner review before merge. ```sh pnpm exec vitest run --maxWorkers=2 \ packages/adapter-utils/src/acpx-engine/execute.test.ts \ packages/adapters/claude-local/src/server/execute.remote.test.ts \ packages/adapters/codex-local/src/server/execute.remote.test.ts \ packages/adapters/claude-local/src/server/acp.test.ts \ packages/adapters/codex-local/src/server/acp.test.ts PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB=1 pnpm exec vitest run --maxWorkers=2 \ server/src/services/ssh-remote-workspace.integration.test.ts pnpm exec vitest run packages/adapter-utils/src/acpx-engine/remote-spawn-smoke.test.ts pnpm --filter @paperclipai/adapter-utils typecheck pnpm --filter @paperclipai/adapter-claude-local typecheck pnpm --filter @paperclipai/adapter-codex-local typecheck pnpm --filter @paperclipai/server typecheck ``` The new admission and staging cases failed before the source fix. The first whole-heartbeat follow-up test also changed an agent setting between turns. That correctly reset the session. The fixture now keeps those settings unchanged and verifies the resumed conversation. Running both engine cases together also exposed duplicate company prefixes and environment names in the fixture; each case now uses its own names. The SSH qualification uses a real isolated OpenSSH server, real Postgres, real ACPX runtime and bridges, and a synthetic ACP provider with a selected test account. It does not call a live provider or run an agent on a user's computer. ## Risks The change affects the shared ACP staging path, restricted to SSH targets that declare in-place realization. Sandbox staging retains its prior behavior, including the existing Codex in-place refusal. Copy-mode SSH sessions retain their prior directory layout. Previously saved sessions keep their format; this adds no migration or session reset. ACP still requires its server command on the remote login PATH. Host authentication and local confinement remain CLI-only. Cold controller/provider reconnection and live Claude/Codex provider acceptance are not qualified by this test. No staging deployment or existing agent configuration is changed by this pull request. ## Model Used OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through the Codex harness, with xhigh reasoning effort and code tools. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
9911b7052f |
Expose continuation retry keys and preserve account-repair resumes (#22046)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Runner gives agents a tool to report work and wait for a later check. > - That tool requires a stable retry key for each explicit wait. > - Codex can hide the wait fields when it renders our nested schema. > - Hidden fields make a correct report harder to construct. > - This pull request changes the provider schema structure and preserves its rules. > - Agents can see the required fields before they submit a report. ## Linked Issues or Issue Description **What happened?** The completion tool appears in Codex code mode with `continuation?: unknown`. An agent can omit the required retry key and receive a rejected report. The top-level schema was fixed in #21398. The nested continuation still uses the same problematic structure. **Expected behavior** Codex must show the required `kind`, `summary`, and `idempotencyKey` fields. Invalid reports must still fail validation. **Steps to reproduce** Render `PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA` with the public Codex code-mode renderer at `b271854568d6c9282e999d6f36e5e85f447d027d`. Its `render_map` function processes `allOf` before sibling properties. The conditional-only branch renders as `unknown` and hides those properties. Source: https://github.com/openai/codex/blob/b271854568d6c9282e999d6f36e5e85f447d027d/codex-rs/code-mode-protocol/src/json_schema_types.rs#L127 **Paperclip version or commit** Baseline: `01451fae5b25f784956e9932f12031dc194ac247`. The first complete CI browser attempt also exposed an intermittent account-repair race. Repair restores the task and resolves its recovery action, then a sweep can reclassify the same old failure and block it again before the queued reply starts. The repair in this PR honors that exact persisted resolution while holding the existing task lock. A later failed run still escalates. ## What Changed - Express the single provider continuation condition as direct `if` and `then` fields. This is equivalent to its previous `allOf` wrapper. - Keep the canonical output schema unchanged. Keep required retry keys and case handoff IDs. - Add a discovery guard, a 60-case provider/canonical validation comparison, and authenticated HTTP bridge checks. ### Hypothesis and thesis for a fix The nested `allOf` hides fields in the tested Codex renderer. The equivalent direct condition lets that renderer reach the object fields. This belongs in the existing provider compatibility schema. It changes no controller policy, company access, saved state, or retry identity. The experiment proves field visibility. It does not prove which renderer served a historical request or measure model omission rates. - Honor a resolved/restored configuration recovery for the same company, task and failed run before re-escalating. Dispatch checks and recovery for new failures remain intact. - Add a PostgreSQL regression covering repeat sweeps, a new failure identity, an unresolved recovery, and another task's repair. This belongs in the existing locked escalation function; no new state or subsystem is introduced. `service.ts` was already over 1,000 lines. - Define the handoff condition once and explicitly compose both canonical and provider schemas from it, removing the implicit one-element `allOf` assumption raised in review. ## Verification - Built and ran the exact pinned public Codex renderer in a disposable Rust crate. The complete baseline schema renders `continuation?: unknown`. The changed schema renders a nullable object with required `kind`, `summary`, and `idempotencyKey` fields. - The new discovery regression fails on the baseline. The same test passes with the fix. - Runner: `pnpm exec vitest run src/contracts/completion-result.test.ts src/contracts/tool-input-variants.test.ts src/contracts/provider-tool-schema-shape.test.ts src/drivers/runner-tool-bridge.schemas.test.ts src/drivers/runner-tool-bridge.continuation.test.ts` — 48 tests pass. - Runner: `pnpm exec tsc -p tsconfig.json` and `node scripts/generate-semantic-contracts.mjs --check` pass. - Server: the selected `task-monitor.integration.test.ts` test for unfinished monitor waits passes with embedded PostgreSQL. It rejects an unscheduled wait and accepts the saved monitor. - Server: the selected `issue-monitor-scheduler.test.ts` recovery test passes with embedded PostgreSQL. It checks persistence, same-key replay, and one scheduled wake. The fixture's successor run fails its separate responsible-user setup. This is not proof of successful successor execution. - HTTP bridge handler is simulated. It verifies rejection before dispatch, valid monitor/response-wake/handoff reports, retry identity, and authentication. - Recovery regression: baseline 1 failed / 3 passed (the restored task was blocked again); unchanged test after the fix 4 passed. Together with recovery state-read tests: 7 passed. Existing configuration-recovery selection: 4 passed, 108 deselected. - Final completion schema and authenticated HTTP bridge selection: 33 passed. - Local real browser journey with disposable embedded PostgreSQL and ACP/provider fixtures: baseline repeat5 produced 2 failures / 3 passes, matching CI. Fixed repeat5: 5 passed in 1.8 minutes. The test independently checks exactly one successful successor, stored connection binding and persisted reply after reload. - No full local suite, deployed recovery, or probabilistic model result is claimed. Fresh CI and review are required for the updated head. - Review follow-up: 48 focused schema/discovery/HTTP tests pass; `node scripts/generate-semantic-contracts.mjs --check` passes. Fresh CI/review required after the refactor. ## Risks Low runtime risk. The accepted input rules are unchanged. A provider that handles direct conditionals differently could expose a compatibility issue. The canonical validator still enforces the output contract. No migration or saved-session reset is needed. Previously saved state keeps the same format. Recovery now honors existing resolved/restored actions only for the exact failed source run, so a new configuration failure remains eligible for escalation. Company, task, ownership and dispatch checks remain in force. ## Model Used OpenAI GPT-6 Codex agent, with reasoning, tool use, and code execution. The runtime did not expose a more specific model ID. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
f4cb69205e |
Let plugin workers serve connector tools (plugin transport) (#22019)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Plugins can now add connector types to the Connectors catalog (#22004), but only for transports the host already runs (remote MCP, local stdio) > - A plugin cannot yet serve a connector's tools itself, and legacy plugin tools (top-level manifest `tools`) still reach every agent without a connection or install > - A plugin should be able to ship a full connector: settings, credentials, tools, grants, policies and audit, like a built-in one > - This pull request adds the `plugin` transport, the SDK API to serve it, and moves legacy plugin tools under the same activation rules without changing today's access > - The benefit is that any connector can live in a plugin, and agents get plugin tools only when an operator enables them ## Linked Issues or Issue Description Refs #22004 **Subsystem affected** Plugins (SDK, worker protocol, manifest), Connectors (tool access, catalog discovery), tool gateway, database. **Problem or motivation** A plugin connector can only describe an existing transport. There is no way for a plugin worker to serve a connector's tools with per-connection settings and credentials. Legacy plugin tools are visible to every agent as soon as the plugin is enabled, which is the opposite of the connector activation rules. **Proposed solution** Add a `plugin` transport. The gateway keeps every decision (grant, policy, approval, rate limit, audit) and calls the plugin worker with the connection, its settings and a per-call credential. Legacy top-level tools become one implicit connector per plugin. Existing installations keep exactly their current access through a one-time migration. **Alternatives considered** Move legacy tools to connection tool names (`app.<connection>:<tool>`). Rejected: names change, so existing tool policies and agent instructions that name `plugin:tool` would stop matching (a possible widening or loss). Legacy tools keep their names and handlers; only their visibility is now gated by an install of the implicit connector. ## What Changed - `packages/db`: migration `0491` widens `tool_connections_transport_check` with `plugin` (`NOT VALID`, annotated `online_compatible`), and adds `plugin_connector_legacy_access`, seeded with one row per installed legacy-tools plugin and company. - `packages/shared`: method schema gains `settingsSchema` and `tools` (`{ kind: "static", list: [{ name, displayName?, description?, risk, parametersSchema }] } | { kind: "dynamic" }`), only for `transport: "plugin"`; tool names must match `[a-z0-9_]`; plugin-served methods use `none` or `api_key`. The connect API accepts `settings`. - `packages/plugins/sdk`: `ToolRunContext.connection` (`id`, `appSlug`, `methodKey`, `grantId`, `settings`, `credential?`); `ctx.connectors.register(appSlug, toolName, fn)` and `ctx.connectors.listTools(appSlug, fn)`; new `listConnectorTools` RPC; `executeTool` routes connector calls by `appSlug`. A worker refuses to start when a declared static tool (or dynamic lister) has no handler. The test harness gains `executeConnectorTool` and `listConnectorTools`. - `server/src/services/plugin-connector-runtime.ts`: routes one call to the plugin's worker; a stopped worker is a `PluginWorkerUnavailableError`. - Connect flow (`tool-access.ts`): a `plugin` method creates a `paperclip_plugin` application and a `plugin` connection with `config = { sourceTemplateKey, connectionMethodKey, settings }`, validated against `settingsSchema`. Credentials, grants, credential policy, installs and profiles use the existing code. - Catalog: static tools come from the definition, dynamic tools from `listConnectorTools`, with the existing version hashing and retirement. Tool risk comes from the declaration. - Gateway: plugin connections join connected-tool discovery and both execution paths (direct and approved actions). For each call the gateway resolves the grant and, for `api_key`, the credential for that call only. The run context comes only from the session. A stopped worker returns `503 plugin_connector_unavailable` with `retryable: true`. The token broker refuses to export plugin connector credentials. - Legacy tools: a plugin with top-level `tools` and no `apps` gets an implicit connector (slug `default`, named after the plugin, no authentication). Its tools keep their names, handlers and today's access decision, and an agent sees them only when a connection of that connector is installed for it or for the company. The connector's saved action rules (Off, Ask first) can only restrict them. `completeLegacyPluginToolAccess` turns each migration row into such a connection with a company install, at boot and when a disabled plugin is enabled again; it is single-flight across servers, resumes a draft left by an interrupted attempt, and never overrides an operator's later changes. - Catalog: tools a dynamic connector stops offering are retired from discovery; `listConnectorTools` carries the connection's `companyId`, and uses the acting person's grant for personal connections. - Board: the setup flow renders `settingsSchema` with the shared JSON Schema form, sends `settings`, and restores saved settings on resume and reconnect. - `create-paperclip-plugin --template connector` now scaffolds a plugin connector (`apps` + `ctx.connectors.register` + a harness test). SDK README and `PLUGIN_SPEC.md` describe connectors; top-level `tools` stay documented as legacy. - `inferToolRisk` moves to `tool-risk-inference.ts` so the catalog can reuse it. Design notes where the spec left room: - OAuth for `plugin`-transport methods is not supported in this PR (`none` and `api_key` only); OAuth plugin connectors can use `mcp_remote` today. Noted as follow-up. - Board "Test" calls on a plugin connection pass an empty `agentId`/`runId`, because there is no agent run. - Companies created after the upgrade get no automatic legacy connection; they follow the normal activation rules. ## Verification - `server`: `npx vitest run src/__tests__/plugin-connectors-plugin-transport.test.ts` (new): - rules 1-3: a ready plugin and configured accounts give no tools; an install for agent A gives only A the tools; agent B is denied on invocation; - the worker receives `runContext.connection` with the right id, method, grant, settings and the call's credential; spoofed arguments do not change it; each account calls with its own key; results do not contain the key; - invalid settings are rejected (422); a stopped worker is `503 plugin_connector_unavailable` (retryable); a disabled plugin hides the tools; - dynamic tools are listed through the worker and a tool it stops offering is retired; - rule 5: a new installation of a legacy-tools plugin gives no tools; an installation recorded by the migration keeps the same tool names for every agent, through one company-wide connection (two concurrent carry-overs make one; an interrupted draft is finished; a retry keeps an operator's restriction), and is not also exposed as connection tools; Ask first and Off on the implicit connector restrict the legacy tools; - the token broker refuses to export a plugin connection's credential. - Existing gateway plugin-tool tests (`tool-gateway`, `tool-gateway-service`, `prompt-injection-gateway`) now set up the legacy grant an existing installation has, and pass unchanged otherwise. - Regression: `plugin-connectors-circleback-parity`, `tool-gateway`, `tool-gateway-service`, `prompt-injection-gateway`, `tool-access-service` (846 passed), plus `connector-tool-policy`, `plugin-lifecycle-restart`, `remote-mcp-connectors`, `ai-connection-router` in an earlier run. - UI: `AppsConnect.test.tsx` covers sending plugin settings from the settings schema. - SDK: `tests/worker-rpc-host.test.ts` (start refusal without handlers, connector routing, tool listing). Scaffold: `entrypoints.test.ts`. - `packages/db`: `pnpm typecheck` including `check:migrations`; server layered typecheck (sources and tests); `tsc --noEmit` for shared, SDK, scaffold and UI. ## Risks - Behavior change for new installations: legacy plugin tools no longer reach agents until an operator connects the plugin's connector. Installations that exist at upgrade time keep their tools through the migration rows. - The migration widens a check constraint (`NOT VALID`) and copies plugin × company rows into a new table. Both are fast; the previous release never writes `plugin`. - Calls depend on the plugin worker; when it is down the agent gets a retryable error. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file editing, test execution). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
904c01d1a3 |
feat(mcp): graduate Assistant connections (MCP) out of experimental (#22015)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Assistant connections (MCP) let an outside assistant, or another
Paperclip instance, sign in as a person and use the `/mcp/paperclip`
endpoint
> - The feature was behind the experimental `enablePublicMcp` setting.
The setting was off by default and in practice off on Cloud stacks
> - Instance-to-instance work (one person's agent files a task on a
colleague's instance) fails when the receiving instance has the setting
off
> - This pull request moves the feature out of Experimental. It is now
always on, and a stored or Cloud-managed "off" value is ignored
> - The benefit is that every authenticated instance with a public URL,
including Cloud workspaces, accepts assistant connections with no setup
step
## Linked Issues or Issue Description
**Subsystem affected**
Public MCP (`server/src/services/public-mcp/`), instance settings,
Connectors → Assistant Connection (MCP) setup page, Experimental
settings page.
**Problem or motivation**
A remote MCP connector on one instance cannot use another instance's
`/mcp/paperclip` unless an admin on the other instance finds and turns
on an experimental toggle. On Cloud, the toggle is off and is managed by
the fleet. Instance-to-instance delegation therefore does not work by
default.
**Proposed solution**
Remove the gate. Keep `enablePublicMcp` only as a compatibility key, the
same way `enableApps` was graduated: old stored rows, PATCH bodies and
Cloud managed configs still parse, but the effective value is always
`true`.
**Alternatives considered**
An instance-admin kill switch that defaults ON. I did not keep one. Each
person already controls access: a connection exists only after that
person approves OAuth consent for one company, and the person or an
admin can revoke it. Deployment policy (authenticated mode and a valid
public URL) still decides whether the endpoint exists. A second switch
would add a state that can silently break instance-to-instance work
again. A schema migration was also not needed: the value lives in the
`experimental` JSON column, and the stored key becomes inert.
**Roadmap alignment**
Requested by the maintainer to enable instance-to-instance
communication.
## What Changed
- `packages/shared`: `enablePublicMcp` is a deprecated compatibility
key. The schema default is `true`. The feature catalog entry is
"Assistant connections (compatibility)" with both defaults `true`.
- `server` instance settings: normalization always returns
`enablePublicMcp: true`. The Cloud managed overlay skips the key, so a
fleet value of `false` cannot disable it. Removed the key from the Cloud
staging experimental-key list. Removed the client-mirror policy step
that ran only when the toggle changed.
- `server` public MCP: personal discovery, OAuth, tools, setup and event
delivery no longer read instance settings (`isEnabled()` returns `true`
for the personal endpoint without a DB read). Dot, Grok and Muse agent
connections keep their own experimental settings.
- `server` Cloud paths: the client-mirror sync, the hosted event
authority, the ingress-handoff expiry worker and the idle sleep proof
treat the front door as enabled. The warm-standby `503
workspace_unclaimed` behavior is unchanged.
- `server` Dot/Grok gates: they no longer also require
`enablePublicMcp`. Error messages no longer tell people to enable
Assistant connections.
- `ui`: removed the Experimental toggle, the "Enable assistant
connections / Open Experimental settings" block on the Assistant
Connection page, and the "Enable Assistant connections (MCP)" hint in
Dot setup. Updated the Dot and Grok copy.
- Storybook: deleted the Experimental-setting story and removed the
"enable the experiment" step from the journey and presenter.
- Docs: `doc/public-mcp.md` ("Enable an instance", "Start from
Connections", `GET /api/mcp/setup`), `doc/openai-dot-runner.md`,
`doc/idle-grok-dispatch.md`, and the agent-access map.
- Tests: new red/green tests for "enabled with no setting stored" and "a
stored or managed off value is ignored". Removed the tests for the
"disabled" behavior, which no longer exists.
## Verification
- Red/green: with the old source and the new tests,
`instance-settings-readonly.test.ts`,
`instance-settings-service.test.ts` and `public-mcp.test.ts` fail (4
failures, and the public-MCP suite fails in `beforeAll` because
`isEnabled()` was `false` with no setting stored). With the new source
they pass.
- `server`: `public-mcp.test.ts`, instance-settings (readonly, service,
managed overlay), `managed-config`, `cloud-event-authority`,
`events-work`, `dot-runner`, `dot-oauth-onboarding` and
`agent-runtime-assignments`. 354 passed.
- Cloud client-mirror lifecycle
(`client-mirror-lifecycle.postgres.test.ts`, skipped in CI) passed
against a local Postgres 17 with
`PAPERCLIP_MCP_SLEEP_TEST_DATABASE_URL`. 6/6, plus `events-work` 28/28.
- Idle and sleep: `idle-incoming-wake` (service and route),
`idle-deadline-proof`, `idle-incoming-wake-capability`,
`idle-sleep-proof`, `client-mirror-ack`, `recovery-deadline-acceptance`
and `idle-completed-history` pass. The warm-standby test now also
asserts that discovery after the claim does no SQL read.
- `ui`: `InstanceExperimentalSettings`, `AssistantConnection`,
`NewAgentDialog`, `NewAgent` and `ExternalAgentInviteDialog.muse` pass.
267 passed.
- Typecheck: `packages/shared`, `server` and `ui` pass. `node
scripts/check-maps.mjs` passes.
- `pnpm verify`: see the CI checks on this PR.
- After the deploy: confirm
`/.well-known/oauth-protected-resource/mcp/paperclip` and `/mcp/setup`
return 200 on paperclip.staging without changing any setting.
## Risks
- Behavior change: instances that had the setting off now serve
discovery, OAuth and `/mcp/paperclip`. Security invariants are
unchanged: the endpoint is still mounted only in authenticated mode with
a valid public URL, OAuth still needs a real signed-in user's consent,
local implicit board authority cannot approve, and revocation works the
same way.
- Cloud sleep: on a managed stack, the MCP sleep proof blocks sleep
until the client mirror publishes the tenant front door to Cloud. The
client-mirror sync runs at boot and does this once. Stacks that already
had the flag on use this path today. A stack whose Cloud connector
cannot publish the mirror would stay awake. Watch fleet sleep after the
deploy.
- Personal public-MCP requests now read instance settings one time less.
- Fleet admin: the Cloud fleet catalog can still show and set
`enablePublicMcp`. The value is ignored. Removing it from the fleet
catalog is a separate change in the Cloud repo.
- No migration. The `0354` trigger still compares the stored key. That
causes at most one extra connector-runtime invalidation if an old client
writes the key.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, test execution).
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
b1efe32c60 |
feat(connections): name and guide connections to another Paperclip instance (#22018)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Each Paperclip instance serves an assistant connection (MCP) at `/mcp/paperclip`, and any instance can connect a remote MCP server by its address > - So one instance's agents can file and follow tasks on another instance, for example a colleague's > - But the other instance's tools look like the agent's own Paperclip tools: same product, similar names, and the connection prefix was a generic internal link key > - An agent can then file local work on someone else's instance, or the reverse > - This pull request recognizes a Paperclip address, names the connection and tool prefix after that instance, adds agent instructions, and refuses a connection to the same instance > - The benefit is that agents can tell their own Paperclip from a connected one ## Linked Issues or Issue Description **Subsystem affected** Connections: "Connect your own MCP server" (generic remote MCP) and the tool gateway names that agents see. **Problem or motivation** When instance A connects instance B through `/mcp/paperclip`, A's agents get B's `paperclip_create_task` and other tools. The tool prefix came from an internal key (`app-gallery🔗<uuid>`), so native runners saw `app_mcp_app_gallery_link_paperclip_create_task_…`. Nothing told the agent that the tools act on a different instance. An agent could send internal work to another organization by mistake. **Proposed solution** Recognize an address whose path is `/mcp/paperclip`. Use only the typed address, never data from the remote server. Name the connection after the host (`acme Paperclip`). Use that name as the tool prefix for these connections only. Add default agent instructions. Refuse the instance's own address with `paperclip_self_connection` (422). **Alternatives considered** Read the company name from the remote `paperclip_connection` tool. This needs an extra authenticated call during setup, and it puts remote-controlled text in names and instructions. The host is enough to identify the stack. Require approval for each write. We rejected this: actions start on, the same as other connections. **Roadmap alignment** Supports instance-to-instance work through existing MCP connections. It adds no new transport. ## What Changed - `packages/shared/src/paperclip-peer.ts`: detect a Paperclip MCP address, derive a label and name, compare with own origins (loopback hosts on the same port are equal), and build default agent instructions. - `server/src/services/tool-access.ts`: default name and default agent instructions for a new Paperclip connection. Instructions that the person supplies are kept. - `server/src/routes/tool-access.ts`: refuse the instance's own address before any network request. - `server/src/services/tool-gateway.ts`: use the prefix recorded on a Paperclip connection (`paperclipPeerToolNamespace`, derived from its address at creation). Renames never change it. Other connections, and Paperclip connections made before this change, keep their current tool names. - `ui/src/pages/apps/generic-mcp-connect.ts`: same default name in the setup flow. - `doc/connections/GENERIC-REMOTE-MCP.md`: new section "Connecting another Paperclip instance". ## Verification - `packages/shared`: `npx vitest run src/paperclip-peer.test.ts`, 20 passed. - `server`: `npx vitest run src/__tests__/generic-mcp-connection.test.ts`, 98 passed. The naming, instructions, self-connection and tool-prefix tests fail on the base revision and pass with this change (red/green). - `ui`: `npx vitest run src/pages/apps/generic-mcp-connect.test.ts`, 29 passed. - `tsc --noEmit` passes for `packages/shared` and `server`. - Live check with two local instances. Instance B was in authenticated mode on port 3201 with assistant connections on. Instance A was on port 3202. - A connected to `http://localhost:3201/mcp/paperclip`. The name was `localhost-3201 Paperclip`. A registered with B by dynamic client registration and asked for read, write, configure and offline access. - B's consent page showed "Connect Paperclip localhost-3202 to Paperclip". After approval, A had all 37 tools active, writes included. - From A, `paperclip_connection` returned B's company. `paperclip_create_task` created `ACM-1` on B. - An agent session on A listed `mcp.localhost-3201-paperclip-…:paperclip-create-task` (runner name `app_mcp_localhost_3201_p_paperclip_create_task_…`). Before the gateway change, the name was `app_mcp_app_gallery_link_paperclip_connection_…`. The run received the connection instructions. - Connecting A to `http://localhost:3202/mcp/paperclip` returned 422 `paperclip_self_connection`. ## Risks - Low risk. Only connections whose address path is exactly `/mcp/paperclip` change. Other connections keep their names, instructions and tool names. - A Paperclip connection created before this change keeps its original tool names, because only connections that record `paperclipPeerToolNamespace` at creation get the new prefix. Saved exact tool-name rules and pending approvals for those connections keep matching. They also get no default instructions; people can add them. - Native runners keep only 20 characters of the namespace (`mcp_` uses 4), so long host labels are cut. The tool part stays complete. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, browser pane). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
1d2b669e7a |
fix(ssh): allow CLI agents on volume-free servers (#21957)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - An SSH environment runs an installed harness on a computer the operator controls. > - Volume-free Cloud servers require durable task files outside the controller. > - The current admission path accepts native sandbox workspaces and rejects existing SSH CLI agents before execution. > - The remote workspace owner already provides saved versions and a single-writer fence. > - This pull request gives that owner an SSH archive transport and admits the existing Claude and Codex CLI adapters under its authority. > - The benefit is SSH task execution without a controller volume or a new environment type. ## Linked Issues or Issue Description **What happened?** A task assigned to an existing SSH Claude Code agent fails on a volume-free Cloud server. It reports that execution requires native Paperclip Runner and remote workspace storage. The failure occurs before provider work starts, even when SSH and the configured AI account are valid. **Expected behavior** An SSH CLI agent can use the configured Paperclip AI account and an installed harness. Task files remain durable when the Cloud controller is replaced. The same SSH behavior applies to direct and Tailscale connections. **Steps to reproduce** 1. Configure an SSH environment on a volume-free server with external Postgres, stable encryption, and object storage. 2. Assign a Claude Code or Codex CLI agent to that environment. 3. Give it a task without a project, such as creating `hello_world.txt`. 4. Observe the workspace admission failure before execution. Related work: #21248 adds agent-selected SSH authentication. #20617 adds Tailscale network selection. #15120 and #17291 cover SSH process and lease cleanup. A search of open and closed PRs found no duplicate of this workspace admission fix. ## What Changed - Reuse remote workspace preparation, archives, saved versions, and single-writer admission for SSH targets. - Add an explicit file-sync capability to the existing SSH command runner. It streams archive files with bounded deadlines and private temporary files. Ordinary SSH runners keep their previous capabilities. - Run the existing CLI adapter in the remote workspace. Bind both the target and its SSH command specification to that directory. - Admit a direct SSH adapter on a volume-free server only when its durable workspace, environment, lease, and path agree. Local filesystem authority remains rejected. - Preserve the server-owned remote workspace receipt when selecting the legacy runtime. - Reuse the workspace finalization lock for a legacy run only when its company, workspace, writer, epoch, and lease receipt match. A claimed token can finish and clear itself after another task reserves a successfully saved shared workspace. Storage writes still require the current workspace authority. - Transfer recovered copies to SSH through the verified workspace archive format. Sandbox recovery retains its existing directory transfer. - Document Node.js, Git, explicit `engine=cli`, and uncertain-process limitations. No UI, Cloud control-plane configuration, schema, or deployment change is included. The remote workspace service owns this change. The shared SSH utility adds file transport because its existing authentication and stream cleanup must remain the only owners of SSH credentials. The heartbeat changes pass the storage authority through existing preparation, selection, and finalization boundaries. The finalization owner extension avoids a separate copy-back lock for SSH. Existing native callers keep their prior admission contract. The existing SSH utility and heartbeat test files are already large. The added code stays beside their existing stream lifecycle and shared fixtures. A larger extraction would widen this compatibility fix. ## Verification - Red-green tests reproduce SSH rejection and verify admission only with remote storage authority. - A real isolated OpenSSH fixture exercises archive capture, a replacement database client, a saved-workspace restore to another allocation, and a failed SSH transfer. Failed saves retain the files and block a competing writer. - A whole-heartbeat test uses the real SSH transport and Claude CLI adapter, a synthetic CLI, a selected Paperclip AI account, and fixture object storage. A follow-up resumes the same provider session and its retained history. It makes no provider API calls. The synthetic provider also supplies its task disposition update. - Existing Claude and Codex SSH adapter tests, workspace preparation, and native workspace owner recovery are included in focused checks. - Before the review fixes, clean-checkout verification passed 610 tests in 11 files. This includes the full workspace preparation, runtime selection, runtime execution, environment orchestrator, ephemeral-server, workspace transport, native owner recovery, SSH integration, SSH command, and Claude/Codex remote execution suites. The macOS SSH fixture was enabled with `PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB=1`; Vitest used `--maxWorkers=2`. - An initial run in the main worktree hit a skill-root lookup outside that checkout. The full selected set passes in the clean checkout. The final company-binding type correction changes no executable behavior; all 8 focused selection regressions pass after that correction. - At the initial head `dd77a4d3cf0`, server and adapter-utils typechecks passed, and the clean verification checkout matched its tree `3f90b0681b1004556d1a720ed45fc8d439b04e96`. - Review regressions first reproduced both a lost ownership token after shared-workspace handoff and a rejected recovered-directory transfer. With the fixes, 223 tests in 5 affected suites pass, including real SSH recovery and native owner-restart, save-concurrency, archive transport, and recovery-receipt checks. The handoff test also confirms that a stale owner cannot save again or claim ownership after a new writer takes over. Server typecheck passes after these fixes. The tested review-fix head is `c5182f5d9c56e738e683d9f26b226e9a820bba83`. - [The initial CI server shard](https://github.com/paperclipai/paperclip/actions/runs/44009944657/job/133794523181) failed on an assertion still expecting the old native-sandbox-only error. Its unsupported sandbox adapter remains rejected; the assertion now matches the supported-remote-environment error. After updating that assertion, all 115 tests in the workspace lifecycle suite pass. Together with the 5 affected suites, this gives 338 passing tests for the review fixes. - `pnpm verify` returns 2 and requests broad CI coverage for the shared/runtime change. The full local suite was not substituted for CI. Final-head [CI](https://github.com/paperclipai/paperclip/actions/runs/44012991355) is green on `c5182f5d9c56e738e683d9f26b226e9a820bba83`: 58 checks pass and 3 are skipped, with no failures or pending checks. Typecheck, build, end-to-end, and the aggregate verification gate all pass. Greptile is 5/5 on this head, security scan passes, and there are no unresolved review threads or merge conflicts. Review-fix checks: ```sh PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB=1 pnpm exec vitest run --maxWorkers=2 \ server/src/services/ssh-remote-workspace.integration.test.ts \ server/src/services/native-runtime/native-workspace-owner-restart-recovery.test.ts \ server/src/services/remote-workspace-transport.test.ts \ server/src/services/remote-workspace-recovery-receipt-fallback.test.ts \ server/src/services/remote-workspace-save-concurrency.test.ts pnpm exec vitest run --maxWorkers=2 server/src/services/remote-workspaces.integration.test.ts pnpm --filter @paperclipai/server typecheck ``` ## Risks This extends the remote workspace owner to another transport and allows qualified SSH CLI execution on volume-free servers. It changes remote file placement to a task directory under `.paperclip-workspaces`. It does not import an existing controller-local workspace. The installed harness uses its existing adapter. Set `engine=cli` explicitly; ACP archive staging does not support these in-place workspaces. This does not qualify native macOS provider packs or change an agent's engine or permission settings automatically. An unknown remote process after SSH loss remains held until it can be reconciled. This change does not add automatic reconciliation of that process. SSH computers are never stopped or deleted. Real provider acceptance and a hosted staging journey have not been run for this revision. ## Model Used OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through the Codex harness, with xhigh reasoning effort and code tools. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
7f9867895c |
fix(ui): keep automated work out of personal recents (#22024)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The sidebar helps each person return to their own work. > - A task visit previously added any readable task to personal recents. > - Automated updates also moved old tasks above newer personal work. > - The Mine inbox already defines personal participation. > - This pull request applies that rule to recent task candidates and preserves their order during background updates. > - Users can see current task status without a stream of unrelated automated work. ## Linked Issues or Issue Description **What happened?** Routine tasks and imported GitHub review tasks appeared in personal recents after a read. Later agent updates moved these tasks up the list. A connected account or stored creator ID could make these tasks look like personal work. **Expected behavior** A task must pass the viewer's existing Mine participation rule before it appears in personal recents. Routine ownership, connected-account provenance and reads alone do not qualify. A viewer can qualify through manual creation, assignment, a direct comment, an allowed user action or a live request addressed to them. Inbox archive state does not remove personal history. Passive reads and machine updates must not advance its order. **Steps to reproduce** 1. Open an automated routine task or imported review task without participating in it. 2. Check the sidebar recents. 3. Let an agent update an older task while newer personal work is in the list. 4. Before this fix, the automated task appears and background updates can move older tasks up. ## What Changed - Add a viewer participation field to bounded navigation summaries. Reuse the canonical Mine query and existing access checks. The field is a read projection; no database migration is needed. - Show only confirmed personal tasks. Remove old nonparticipants after a successful read. Do not trust participation from local storage or full task caches. - Keep status and title snapshots current without changing personal order. Explicit local edits and comments can advance recency. - Migrate browser history once to a new storage version. Older tabs cannot restore machine-driven ordering. - Keep confirmed rows visible if a new batch request fails. Keep these facts within the current account and company. Hidden candidates do not bypass the one-second reorder delay. - Record sidebar renames as local activity. Place a first passive visit below existing history. - Use the saved comment time for comments sent with reassignment or custom run settings. Pending sends do not advance recency. - Keep readable subtasks as context beneath qualifying parents. Keep inbox archive independent of recents. - Update the design rules, UI behavior notes, regression tests and Runner source contract pin. ## Verification - Current head: `92ece0e61859a6c54b714b3611f062ff9b5633bb`. The PR merges cleanly with current master. - Latest red/green: both configured-comment cases failed before the fix and now pass. Reassignment and custom run settings advance recency only after the comment saves, using its saved time. - Latest local checks: 339 tests passed across IssueDetail and recent storage, hooks and sidebar. UI typecheck and diff checks passed. - Earlier local coverage: 592 targeted API/UI tests passed. After the master conflict resolution, all 29 overlapping Gmail tests and the 548-input source registry check passed. - Both Greptile and Paperclip Review report 5/5 on the current head. All four review threads are resolved. - Current-head [CI attempt 2](https://github.com/paperclipai/paperclip/actions/runs/44132164473) passed, including the final verify gate, build, typecheck, browser shards, serialized tests, Runner checks and all general-test shards. The workspace-a (1/2) retry passed after the first attempt hit an asynchronous jsdom/Radix event error in NewAgentDialog. - `pnpm verify` requires broader CI because DESIGN.md changed. No full local suite or deployed-browser acceptance was claimed. This change is not deployed. ## Risks - Unknown eligibility stays hidden until the summary succeeds. Failed requests preserve saved candidates and previously confirmed state within the current account and company, including after batch changes. - This intentionally removes automated tasks from old personal history when the viewer has no qualifying participation. - Readable subtasks under a personal parent remain context. They do not become independent recent entries from machine activity. - No task ownership, routine definition, inbox membership or permission rule changes. ## Model Used OpenAI GPT-6, running as Codex, with reasoning, repository tools and focused test execution. No additional model workers were used. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
8172d27089 |
feat(cloud): browser product analytics through a same-origin PostHog proxy (#22012)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip Cloud runs the same app for hosted customers, and the same UI ships in the npm package. > - The PostHog project for Cloud gets only server events today. It has no page views, sessions, replays or people. > - So the Product and Web analytics pages are empty, and we cannot see how Cloud users move through the board. > - This pull request adds browser analytics for Cloud only. It is off until an operator sets two switches on a Cloud stack. > - Self-hosted installs do not change: they never download posthog-js and never serve the PostHog proxy. > - The benefit is real page views, sessions, heatmaps, Web Vitals and masked session replays for Cloud, linked to the user and the workspace. ## Linked Issues or Issue Description **Subsystem affected** Board UI (analytics bootstrap and privacy markers), server session payload and a new same-origin proxy route, shared validators. **Problem or motivation** Cloud sends only server events to PostHog. There is no browser SDK, so PostHog has no page views, sessions, replays or identified people for Cloud. We cannot see where Cloud users get stuck. **Proposed solution** The signed-in session gives the UI a PostHog config only on a Cloud-managed stack with `PAPERCLIP_POSTHOG_PROJECT_TOKEN` and `PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`. The UI loads posthog-js after the page settles. Events go through a strict same-origin proxy at `/_ph`, so ad blockers do not drop them. Replay masks all text and all inputs by default. **Alternatives considered** Bake a key into the UI build: refused, because the same build ships to self-hosted users. A generic reverse proxy: refused, because it would forward any path. Mask only content areas: refused, because a missed surface would leak; masking is deny by default. **Additional context** This is the browser part of the Cloud direct PostHog plan. The server direct sender is already on master (#22006). Fleet configuration is a separate change. PostHog person deletion on account deletion is a follow-up. ## What Changed - Uses the shared Cloud PostHog config (`resolveCloudPostHogConfig` in `server/src/services/cloud-posthog-config.ts`, already on master from the server direct-sending change). This PR does not change it. - `server/src/services/cloud-posthog-browser.ts`: `resolveBrowserAnalyticsConfig` returns `{ token, apiHost: "/_ph", uiHost, environment, stackId, replayEnabled }` only when `PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`. `environment` is always set: the explicit variable, else `staging` for a `*.staging.paperclip.app` host, else `production`. - `GET /api/auth/get-session` carries the new optional `browserAnalytics` field (the existing signed-in bootstrap request, so no new request on the cold path). `packages/shared` has `browserAnalyticsConfigSchema` and the session schema field. - `server/src/routes/posthog-proxy.ts`: a strict proxy, mounted before the body parsers and only when browser analytics is on. It forwards only these requests and answers 404 to all others without contacting PostHog: - `POST /e/`, `/i/v0/e/`, `/batch/`, `/s/`, `/flags/`, `/decide/` to the ingest host. - `GET /array/<token>/config(.js)` and `GET /static/[<version>/]<name>.js` to the assets host (derived from the ingest host). - `stream.pipeline` joins the streams, so an error on either side (PostHog closes the connection partway through a response, or the browser goes away) closes both and never goes unhandled. It builds a new header set from an allowlist plus `X-Forwarded-For`. It never forwards the inbound Host, Cookie or Authorization headers. It drops `Set-Cookie` from responses. Bodies stream; nothing is buffered. It refuses bodies over 64 MiB (413, also for chunked bodies that grow past the limit) and limits requests in flight to 16 per client address and 256 in total (429). - `ui/src/lib/analytics/product-analytics.ts` (the only module that talks to posthog-js) and `ui/src/components/ProductAnalyticsGate.tsx`: - posthog-js loads after the page settles (or at a 15 s deadline), only when the session has a config. It loads as PostHog's browser script `/_ph/static/array.js` through the proxy, the same way posthog-js itself loads its extensions (recorder, web vitals). It is not an npm dependency and is in no bundle chunk. - Init: page views on history change, page leave, autocapture, Web Vitals, heatmaps, `person_profiles: "identified_only"`, `tracing_headers` for our own host only, replay only when `replayEnabled`. Surveys, product tours, web experiments and conversations are off. - Super properties on every event: `deployment_source: "cloud"` and `environment`. - After sign-in: `identify(session.userId, { email, name })` (person properties only). `session.userId` is the authenticated actor's user id verbatim (for example `paperclip-id:...`): `GET /api/auth/get-session` copies `req.actor.userId` into it, and server events use that same actor id as `distinct_id`, so browser and server events land on one person. Tests: `auth-routes.test.ts` (the session returns the actor id verbatim) and `ProductAnalyticsGate.test.tsx` (identify uses it) and `group("workspace", stackId)`. On sign-out: `reset()`, then the super properties again. `useSignOut` calls it before it leaves the page, because Cloud sign-out navigates away while the session query is still populated. - Privacy (`ui/src/lib/analytics/privacy.ts`), deny by default: - Replay masks every text node (`maskTextSelector: "*"` with `maskTextFn`) and every input value (`maskAllInputs`). - Only elements with `ANALYTICS_UNMASK_PROPS` show their text: sidebar items whose label is a fixed string (`analyticsChrome`, added at the 99 call sites with literal labels), and a shared `Button`, `Label`, `TabsTrigger` or `EmptyState` only when its caller passes `analyticsChrome`. None of them opts in by default, because they also render customer text (agent names, document titles). Sidebar items with dynamic labels (recent tasks, agents, projects) stay masked. - Replay masks attribute values too (`maskAttributeFn`, deny by default). Only layout attributes (`class`, `style`, `role`, `data-state`, SVG geometry), rrweb metadata and stylesheet links keep their values. `title`, `aria-label`, `alt`, `placeholder`, `src`, `href`, `data-*` and element references (`id`, `for`, `aria-labelledby`, `aria-describedby`, `aria-controls`, which often embed names or slugs) are always masked, even on unmasked chrome. So the organization switcher's `aria-label`, task titles in `title` attributes, image sources and download links with file paths never reach a replay. - `before_send` (`scrubCapturedEvent`) drops the `title` property from every event, because posthog-js copies `document.title` (task and organization names) into page views. Every URL string in every event, including replay meta events, keeps only its origin and path: query and hash values never leave (they can hold tokens, `code`/`state`, file paths or search text), and the token segment of `/board-claim/<token>` and `/invite/<token>` is redacted. It recurses only into plain objects and arrays, so the `Date` timestamp stays intact. - `ANALYTICS_MASK_CLASS` keeps customer content masked even inside unmasked chrome: `MarkdownBody` (task and issue bodies, comments, chat messages, documents and artifact markdown), `MarkdownEditor`, the task chat thread, the issue chat thread, the comment timeline, the file viewer (source, markdown and CSV views) and the organization name in the organization switcher. Text in any `contenteditable` editor is always masked. - `ANALYTICS_NO_CAPTURE_CLASS` (`ph-no-capture`, a blank box in replay) on every password-type `Input` (about 40 secret, token and API key fields), environment variable values and new secret values. - Autocapture never records element text or attribute values (`mask_all_text`, `mask_all_element_attributes`). - Connected-account content (Google user data and Slack data: email bodies, calendar events, Slack messages in tasks, chat, tool results, previews) never appears unmasked in a replay. Replay masks all text by default; nothing that renders connected-account content is in the unmask allowlist; autocapture records no element text anywhere (`mask_all_text`). `ui/src/lib/analytics/unmask-allowlist.test.ts` pins the allowlist: only 7 files may spread the unmask attribute, sidebar opt-ins need a literal label, and any `analyticsChrome` opt-in on `Button`/`Label`/`TabsTrigger`/`EmptyState` fails until it is added to a reviewed list (empty today). The same test renders Gmail, Calendar and Slack-style tool results next to unmasked navigation and checks they are masked. - Guard test: UI code must never call `capture()` with a `PAPERCLIP_EVENTS` name, so each event has one sender. - Docs: `doc/cloud-browser-analytics.md` (switches, per-stack opt-out, proxy allowlist, identity, privacy) and a link from `doc/observability.md`. - No new npm dependency and no lockfile change: posthog-js comes from PostHog through the proxy at run time. (An earlier revision added `posthog-js` to `ui/package.json`; the Runner support suite requires every `ui` dependency in the reviewed lockfile, which a pull request cannot update, so the script approach replaced it.) ## Verification - `pnpm verify`: see the result below. - Focused tests: - `server/src/__tests__/cloud-posthog-browser.test.ts`: exposure matrix (self-hosted with every switch set, Cloud without token, without stack ID, without the browser switch, switch not `1`, enabled, replay off), environment fallback, proxy mount only when enabled, allowed routes, 404 for disallowed methods and paths (including `//host` and `..` paths) with no upstream contact, Host/Cookie/Authorization stripped, `Set-Cookie` dropped, 502 when PostHog is down, and no unhandled error when PostHog closes a response partway (red on the old `pipe()` code, green now). - `server/src/__tests__/auth-routes.test.ts`: the session carries `browserAnalytics` only on Cloud with the token and the switch. - `ui/src/lib/analytics/*.test.ts`, `ui/src/components/ProductAnalyticsGate.test.tsx`: no import of posthog-js without a config or when signed out; load after the page settles, once; identify, group, reset with a mocked posthog; email and name never become event properties; deny-by-default replay masking; guard test. - Real run (local, headless Chromium, production UI build, never the real PostHog project): - Self-hosted server, no env: 0 requests for PostHog's script and 0 requests to `/_ph` in 9 cold loads and in a 40 s session with navigation. `browserAnalytics` is `null`. `/_ph/e/` falls through to the UI. - Cloud config: a full Cloud boot needs S3, a managed database and the control plane. So a small local stand-in served the same production UI build, mounted the real proxy from `server/src/routes/posthog-proxy.ts`, added the real `resolveBrowserAnalyticsConfig()` output to the session, and forwarded other API calls to the local server. `PAPERCLIP_POSTHOG_HOST` pointed at a local capture server. - Captured through `/_ph` only (0 requests to any posthog.com host): `$pageview` on each client navigation (5), `$identify` with `$set: { email, name }`, `$groupidentify`, `$groups: { workspace: <stack id> }` on events, `environment` and `deployment_source` on every event, `$web_vitals`, `$autocapture` with no `$el_text`, `$$heatmap`, and 10 `$snapshot` replay events. A search of every decoded `/e/` and `/s/` payload (events, replay text and replay attributes) found the email only in `$identify`'s `$set`, and found none of: the task body, the typed comment, the task title, the organization name. No Cookie header reached the capture server. 96 of 113 API requests carried `X-POSTHOG-SESSION-ID` (the others ran before posthog-js loaded). - Client-side visits to `/invite/INVITESECRET123` and `/cli-auth/abc?token=CLISECRET456` reached PostHog as `/invite/REDACTED` and `/cli-auth/abc` (no query); neither secret was in any payload. - Disallowed proxy requests (`PUT /_ph/e/`, `GET /_ph/api/projects/`, `POST /_ph/static/x.js`) answered 404. - Sample replay payload (decoded rrweb text nodes from a captured `/s/` request). The task body, the typed comment, the task title, the organization name and the email were not in any replay payload: ```json {"text_nodes": [ {"parentTag": "title", "textContent": "****** ** * *********"}, {"parentTag": "a", "textContent": "**** ** **** *******"}, {"parentTag": "span", "textContent": "****** **"}, {"parentTag": "span", "textContent": "*** ****"}, {"parentTag": "span", "textContent": "Tasks"}, {"parentTag": "span", "textContent": "Inbox"}, {"parentTag": "h2", "textContent": "******* *******"}, {"parentTag": "p", "textContent": "****** *** * ******* ** ******"} ]} ``` - Cold load, 9 fresh-profile loads each, median, same stand-in with analytics off and on: | | DOMContentLoaded | Board content visible | | --- | --- | --- | | Analytics off | 128 ms | 336 ms | | Analytics on | 126 ms | 334 ms | Final head. The difference is inside run-to-run noise (earlier pairs: 332/335 ms and 335/348 ms). PostHog's script loads only after the content is visible. ## Risks - Inert by default. Without a Cloud-managed stack, a project token, a stack ID and `PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`, the session field is `null`, the proxy is not mounted and no analytics code runs. The OSS package does not change behavior. - Per-stack opt-out: `PAPERCLIP_POSTHOG_REPLAY_ENABLED=0` turns replay off; unsetting `PAPERCLIP_POSTHOG_BROWSER_ENABLED` turns all browser analytics off. Both apply on the next restart. - Replay text shown in the clear comes only from fixed sidebar labels and from shared components whose caller opts in. Today no `Button`, `Label`, `TabsTrigger` or `EmptyState` call site opts in, so replays show layout, clicks and navigation with most copy masked. Opting in fixed-label call sites is a follow-up. Review sample replays on staging before production. - Image `src` values are masked, so images record as empty boxes. Sandboxed iframes (HTML artifacts, MCP apps) also record as empty boxes. Replays therefore show layout and product copy, not customer media. - PostHog's script is not version-pinned: the assets host serves its current browser build, as for any PostHog snippet install, and posthog-js already loads its extensions from that host at run time. It runs only on Cloud stacks with the browser switch on. - The proxy needs no sign-in, like PostHog's documented proxies: posthog-js sends some events while a page unloads, and the proxy can only reach the two PostHog hosts, on the listed paths, with the public project token. Body size and in-flight limits bound the load one client can add. - posthog-js rejects bots (including headless browsers) on its own, which is the wanted production behavior. - `SidebarNavItem.production.tsx`, `Sidebar*.tsx` and the shared `ui/*` components changed by one attribute each; no visual change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, headless browser runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
7f1f0eef67 |
fix(google-workspace): request free/busy with read & write Calendar, and update connector docs (#22026)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The built-in Google Workspace connector gives agents Gmail, Drive and Calendar through one connection, behind an experimental setting > - The user picks each service as read only or read & write. Paperclip then requests only scopes from a fixed list of 14 > - Read & write Calendar requested `calendar.calendarlist.readonly` and `calendar.events`. Our code assumed `calendar.events` also covers free/busy lookups > - Google's REST `freeBusy.query` does not accept `calendar.events`. So the REST `suggest_time` tool cannot read free/busy on a read & write grant, and falls back to reading each attendee's events > - This pull request adds `calendar.events.freebusy` (already one of the 14) to the read & write Calendar selection of the unified connection, and stops treating `calendar.events` as implying free/busy > - The benefit is that `suggest_time` on REST can see coworkers who share only free/busy, and the stored grant no longer claims a permission that Google did not give. It also brings three Google connector planning docs up to date ## Linked Issues or Issue Description Refs #22016, #22017, #22010, #22014 **What happened?** The read & write Calendar selection of the unified Google Workspace connection requests `calendar.calendarlist.readonly` and `calendar.events`. `toolScopes.calendar.suggest_time` lists `calendar.events` as sufficient, and `googleWorkspaceEffectiveScopes` treats `calendar.events` as implying `calendar.events.freebusy`. Google's two references differ: - REST [`freeBusy.query`](https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query), checked 2026-11-17: "This request allows authorization with at least one of the following scopes:" `calendar.readonly`, `calendar`, `calendar.events.freebusy`, `calendar.freebusy`. `calendar.events` is not in the list. - Google's hosted Calendar MCP [`suggest_time`](https://developers.google.com/workspace/calendar/api/v3/reference/mcp/tools_list/suggest_time), checked 2026-11-17: "Requires one of the following OAuth scopes:" `calendar`, `calendar.readonly`, `calendar.events`, `calendar.events.freebusy`, `calendar.freebusy`. Here `calendar.events` is accepted. So `calendar.events` is enough for Google's MCP tool but not for the REST endpoint that our REST `suggest_time` uses. **Expected behavior** A user who picks read & write Calendar gets a grant that allows `freeBusy.query`. A grant that does not have the free/busy permission is not recorded as having it. Grants made before this change keep working as read & write. **Steps to reproduce** 1. Call `googleWorkspaceSelectedScopes({ calendar: "write" })`. It returns two scopes, without `calendar.events.freebusy`. 2. Call `googleWorkspaceEffectiveScopes(readOnlyCalendarScopes, [calendar.events])`. It returns `calendar.events.freebusy`, which Google did not grant. 3. With Calendar on the REST transport, `suggest_time` on a read & write grant gets an insufficient-scope answer from `freeBusy.query` and uses the events fallback. ## What Changed - `packages/shared/src/google-workspace-connectors.ts`: - `googleWorkspaceSelectedScopes` adds selection-level scopes from a new `SELECTION_ADDED_SCOPES` map. Read & write Calendar adds `calendar.events.freebusy`. The per-service `calendar.write` profile (`SERVICE_PROFILES["calendar.write"]`) is unchanged, because the Cloud broker matches legacy profiles by exact scope set. - `googleWorkspaceEffectiveScopes` no longer expands `calendar.events` to `calendar.events.freebusy`. `calendar.events` still implies `calendar.events.readonly`. `calendar.readonly` still implies free/busy, which Google's reference allows. - `googleWorkspaceSelectionForScopes` is unchanged. It needs the legacy write profile's scopes, so a two-scope grant and a three-scope grant both read back as read & write. - `toolScopes.calendar.suggest_time` is unchanged. It still accepts `calendar.events`: Google's MCP tool accepts it, and on REST the tool has an events-based fallback that names attendees it cannot read. - Counts: default all-read-and-write selection is now 10 scopes (was 9); all read-only stays 8; the union of all 27 selections stays exactly the 14. - Tests (written first and seen failing on `master`): - `packages/shared/src/google-workspace-connectors.test.ts`: scopes for read and for read & write Calendar; the legacy `calendar.write` profile keeps two scopes; default count 10 and read-only count 8; old two-scope grant, new three-scope grant and partial consent (user declines free/busy) all round-trip as read & write and keep `list_calendars`, `list_events`, `suggest_time`, `create_event` and `delete_event`; no recorded free/busy that Google did not grant. The existing exhaustive test still checks that no selection requests a scope outside the 14. - `server/src/__tests__/tool-access-service.test.ts`: customer-owned Workspace OAuth with read & write Calendar asks Google for all three scopes. With and without free/busy in Google's answer, the connection is active, the Calendar tools are listed, the grant stores exactly what Google granted, and it reads back as read & write. - Stale tests on `master` fixed: `#22014` made Gmail 9 of 9 in the REST tool set while `#22016` still expected 3 Gmail REST tools. `google-workspace-rest-dispatch.test.ts` and `google-workspace-rest-transport.test.ts` now derive the Gmail list from the allowlist and use Chat as the service with no REST tools. - Docs: `doc/connections/GOOGLE-WORKSPACE.md`, `doc/connections/GOOGLE-WORKSPACE-SERVICE-CONSENT.md` and `doc/connections/tool-method-permission-reviews.json` say ten scopes and explain the Calendar change. - Docs: `doc/memory/google-connector-memory.md` (shipped PRs #22010, #22014, #22016, #22017; three Nov 17 decisions; "Where Google content is kept" replaced with #22010's inventory, what deletion keeps and its limits; Scopes section; REST tools status table; still-open list), `doc/plans/2026-11-17-google-workspace-production-checklist.md` (help page and retention audit ticked with #22010; REST tool progress), `doc/plans/2026-11-17-google-workspace-code-fixes.md` (fix 6 done with limits; section 9 status table; fix 10 note). - `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed pins for the changed shared files. Not changed: - `server/src/google-workspace-rest-tools/**`. Another change owns that folder. Its README open question about this scope is now resolved and can be removed there. - The picker disclosure (`googleWorkspaceDisclosure.ts`). Read & write Calendar already says agents "can see your calendars, events and free/busy times". With this change that line is accurate on REST too. Behavior for existing grants: a saved read & write grant without free/busy still reads back as read & write, keeps every Calendar tool, and refreshes without change. Nothing prompts the user to reconnect. A user who chooses read & write Calendar in the picker is asked for the new scope. An account-page reconnect without a new choice still restores the exact saved request, as before. Cloud broker and Google Console: no change needed. `calendar.events.freebusy` is one of the 14 in `workspace.all`, the broker accepts any nonempty subset of `workspace.all` (`doc/connections/GOOGLE-WORKSPACE-SERVICE-CONSENT.md`), and the legacy `calendar.write` profile's exact scope set did not change. ## Verification - `cd packages/shared && npx vitest run src/google-workspace-connectors.test.ts src/app-definitions.test.ts`: 55 passed. On `master` the new shared tests fail (3 failed). - `cd server && npx vitest run src/__tests__/tool-access-service.test.ts -t "free/busy"`: 2 passed. With `master`'s `google-workspace-connectors.ts`: 2 failed. - `cd server && npx vitest run src/__tests__/google-workspace-rest-transport.test.ts src/services/google-workspace-rest-dispatch.test.ts`: 29 passed (4 failed on `master` before this change). - `cd ui && npx vitest run src/features/connections/GoogleWorkspaceServices.test.tsx src/pages/apps/AppDetail.test.tsx`: 115 passed. - `cd packages/shared && npx tsc --noEmit -p .`: clean. - `pnpm verify` exits 2 (a global CI input changed), so required CI supplies the broad coverage. - Docs facts checked against `gh pr view` for #22010, #22014, #22016, #22017, the code, and paperclipai/paperclip-website PR 197 (still a draft; does not mention OpenRouter). ## Risks - Low risk. The submitted set of 14 does not change, and the broker contract does not change. - New read & write Calendar grants record `calendar.events.freebusy` next to `calendar.events`. Code that reads stored scopes sees one more scope. All consumers (callback, refresh, discovery, picker pre-fill) are covered by the tests above. - A read-only Calendar request on an account that Google reports only `calendar.events` for no longer records free/busy. That matches what Google granted; `suggest_time` is then not offered on that grant. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with tool use, web fetch and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
01451fae5b |
Let plugins add connector types to the Connectors catalog (#22004)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use external services through connectors: a catalog of connector types, connections (accounts) per type, and per-agent installs, policies and audit in the tool gateway > - Today only core can add a connector type. Every type is a JSON definition compiled into `@paperclipai/shared` > - Plugins can add agent tools, but those tools skip connections, grants, per-agent installs and the Connectors page > - This pull request lets a plugin add connector types with the same definition schema, and makes them behave exactly like built-in connectors > - The benefit is that a connector can ship as a plugin, and an operator controls it with the same Connectors page and the same access rules ## Linked Issues or Issue Description **Subsystem affected** Plugins, Connectors (tool access), tool gateway **Problem or motivation** A plugin cannot add a connector type to the Connectors catalog. Plugin tools (`tools` in the manifest) do not use connections, credentials per account, agent installs, policies or the Connectors page. **Proposed solution** Add a manifest field `apps` (gated by a new `connectors.provide` capability). Each entry uses the built-in app-definition schema. The host namespaces the slug by plugin key and runs setup, OAuth, discovery, grants, policies and audit through the existing code. This is the first of two pull requests. The second adds a `plugin` transport so a plugin worker can serve the tools itself. **Activation rules (product requirements)** 1. Installing or enabling a plugin grants no tools. It only adds connector types to the catalog. 2. Connecting an account grants no tools. 3. An agent gets the tools only from an agent install or a company install of an active connection. Discovery and invocation both enforce this. 4. A disabled or uninstalled plugin (or an upgrade that removes the app) hides its connector types and connections from the Connectors APIs and they reach no agent. Saved setup survives disable and comes back on re-enable. Uninstall keeps rows archived for audit and revokes credentials. **Alternatives considered** Keep plugin tools (`tools`) as the only plugin path. Rejected: they bypass connections, per-account credentials, per-agent installs and the Connectors page. ## What Changed - `packages/shared`: new capability `connectors.provide`; manifest `apps` validated with `appDefinitionSchema`. The validator rejects apps without the capability, duplicate slugs, host-derived fields (`plugin`, `aiConnectionRouter`, `experimentalFeatureKey`, `availability`), and methods that need provider code in the host (REST adapters, chat channels, AI runtimes). - `packages/shared/src/plugin-apps.ts`: reversible namespaced slugs (`plugin-<hex plugin key>-<slug>`), the catalog entry builder, and `reviewedToolRisk`. - `packages/shared/src/app-definitions.ts`: catalog lookups (`getConnectableAppDefinition`, `getAppStoreDefinition`, ...) also resolve the current plugin apps. The set is replaced on each read of plugin state, so a built-in app is never shadowed. - App definitions can declare `reviewedTools` (reviewed read/write/destructive names and the risk for unlisted tools). Circleback's reviewed risk moves from `server/src/services/connectors/circleback/risk.ts` into `circleback.json`, with the same classification. A copy of the definition now classifies tools the same way. - `validators/json-schema.ts`: `jsonSchemaSchema` moves to its own module to break an import cycle between the plugin and app-definition validators (still re-exported from `validators/plugin.ts`). - `server/src/services/plugin-app-catalog.ts`: reads ready plugins from the `plugins` table and answers "is this connection's connector available". It does not trust in-memory lifecycle events, because several lifecycle managers and processes can share one database. - Gateway: connected-tool discovery and `resolveConnectionGrant` drop connections from an unavailable plugin connector. Built-in connections do not read the plugins table. - Connectors APIs: the gallery lists ready plugin apps (with the same Cloud connector profile filter as core); `listConnections` and `listApplications` hide unavailable plugin connections; setup entry points refresh plugin apps first. - Plugin uninstall archives the plugin's connections through the standard connection removal (grants revoked, owned credentials deleted, rows kept). - UI: the gallery response registers plugin apps for the setup screens; `/apps/connect?source=plugin-…` loads the gallery first and shows an unavailable state when the plugin is disabled. - Docs: `doc/plugins/PLUGIN_SPEC.md` section 11A and the capability list. Design choices where the spec left room (picked to match "a plugin connector behaves like a built-in connector"): - Only `ready` plugins provide connectors. `error` and `upgrade_pending` hide them, the same as the AI connection router plugins. - `rest_api` is rejected for plugin apps in this PR. Core REST connectors need reviewed adapter code in the host, so a definition alone cannot work. The `plugin` transport in the next PR covers that case. - Disabled plugin connections are hidden from list endpoints. Reading one connection by id still works, so audit links keep resolving. ## Verification - `packages/shared`: `npx vitest run src/plugin-apps.test.ts src/validators/ src/app-definitions.test.ts` (416 passed). New tests: manifest validation, slug namespacing, no shadowing of built-in apps, reviewed risk. - `server`: `npx vitest run src/__tests__/plugin-connectors-circleback-parity.test.ts` (new). A test-only plugin (`server/src/__tests__/fixtures/plugin-connectors/circleback-parity/`) ships an unmodified copy of `circleback.json`. The same journey runs against built-in Circleback and the plugin copy with a recorded DCR OAuth + MCP fixture, and must give identical catalog risk/status, suggested defaults and per-agent tool sets. It covers each rule: - Rule 1: the gallery adds only the namespaced type; no connections exist; no agent tool changes. - Rule 2: two signed-in accounts, no agent sees a tool. - Rule 3: an install for agent A gives only A the tools of that connection; agent B is denied on invocation; each account calls the provider with its own credential. - Rule 4: disable hides the type, both connections and applications, removes tools from discovery and invocation (404) and blocks new setup, while built-in Circleback is unchanged; installs and grants are byte-identical; re-enable restores tools with the same names; an upgrade that removes the app hides it; uninstall archives both connections, revokes grants and deletes owned secrets. - Red/green: removing the gateway gate or the declared review makes the test fail. - An env-gated live check (`PAPERCLIP_CIRCLEBACK_LIVE=1`) starts the real Circleback sign-in for both connectors and compares the requests. It never runs in CI. I did not run it for this PR. - Regression: `ai-connection-router`, `connector-tool-policy`, `mcp-apps`, `plugin-lifecycle-restart`, `tool-access-service`, `braintrust-connection`, `remote-mcp-connectors`, `connection-intents-service`, `tool-gateway` (796 passed). - `ui`: `app-connect-policy.test.ts`, `AppsConnect.test.tsx` (new plugin cases) pass. - `tsc --noEmit` for shared, server, ui (only pre-existing ungenerated Storybook catalog errors), plugin SDK and CLI. - `pnpm verify --explain` selects a broad plan because a doc under `doc/plugins` changed; CI supplies that coverage. ## Risks - No migration. Built-in connectors only gain one string check per discovery; the plugins table is read only when a plugin connection is present. - Circleback's reviewed risk is now data. The behavior is the same, and the existing policy tests and new tests cover it. - Connection intents (agent connection requests in chat) still search only built-in apps. Plugin connectors can be set up from the Connectors page. This is a follow-up. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file editing, test execution). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
c652c813bc |
feat(google-workspace): per-service transport switch for REST-backed tools (off by default) (#22016)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use Google Workspace through one built-in `google-workspace` connection and the tool gateway > - Today every Google tool call goes to Google's hosted Workspace MCP servers, which are a Developer Preview and cannot be offered to the public > - #22000 added Paperclip's own Gmail tools over Google's REST APIs in `server/src/google-workspace-rest-tools/`, but nothing calls them yet > - This pull request adds one per-service transport switch and connects the gateway to the REST tools behind it. Every service stays on Google's MCP servers, so production behavior does not change > - The benefit is that a service moves to the REST tools with a one-line, reviewed change once all its tools exist, and moves back the same way ## Linked Issues or Issue Description Refs #22000 **Subsystem affected** Tool gateway and catalog discovery for the built-in Google Workspace connection. **Problem or motivation** Google's Workspace MCP servers are a Developer Preview. Paperclip launches on its own tools over Google's REST APIs. The REST tools exist (#22000), but the gateway cannot call them, and there is no way to choose them per service. **Proposed solution** Add a per-service transport setting (`google_mcp` or `paperclip_rest`) in the shared Google Workspace module. Add one server adapter that is the only importer of the REST folder. When a service is set to `paperclip_rest`, the gateway call path and discovery use the adapter in process. All gateway controls stay the same. **Alternatives considered** A loopback or hosted MCP endpoint for the REST tools. It adds a connection, JSON-RPC framing and the protocol probe to every call, and authenticated public deployments refuse loopback addresses. An environment variable or instance setting. A plain constant keeps every flip a reviewed code change. ## What Changed - `packages/shared/src/google-workspace-connectors.ts`: adds `GOOGLE_WORKSPACE_TOOL_TRANSPORT` (every service is `google_mcp`), `transport` on the result of `googleWorkspaceToolTarget`, and `googleWorkspaceServiceToolNames`. - New `server/src/services/google-workspace-rest-dispatch.ts`: the only importer of the REST folder. It keeps only the bearer token from the gateway's credential headers, passes the gateway's egress-guarded fetch and cancellation signal, and returns either the MCP result or a token problem. `googleWorkspaceRestTransportGaps()` lists allowlisted tools that a `paperclip_rest` service does not implement. Today Calendar is eligible (9 of 9) and Gmail is not (3 of 9); nothing is flipped. - `server/src/services/tool-gateway.ts` (`executeRemoteHttpTool`): for a `paperclip_rest` tool, the gateway rechecks the current grant, calls the adapter, and returns through the same result handling as the MCP path. Google's insufficient-scope answer maps to `oauth_insufficient_scope`. A rejected token forces a refresh and returns `oauth_refreshed_retry_required` without a replay. A passed deadline returns `tool_timeout`. The audit record names the protocol `Google Workspace REST`. The grant recheck is now one shared helper for both paths. A timed-out Google Workspace write, on either transport, now returns `tool_timeout` with a warning that the change may or may not have been made; a timed-out read keeps the plain timeout message. - `server/src/services/tool-access/catalog/discovery.ts`: for a `paperclip_rest` service, discovery and health run one REST probe with the caller's token, then list the REST tools under the same names and scope filter. A 401 refreshes and probes again. A second 401 on a managed grant marks it `needs_reauthorization`. Any other probe failure makes only that service unavailable. - `server/src/google-workspace-rest-tools/`: adds `probe.ts` and its export. Each service has an ordered list of cheap reads with the scopes that allow each (Gmail: `users.getProfile`; Calendar: one calendar list entry, one primary-calendar event, or one minute of free/busy). The probe uses the first read the grant allows. A grant that allows none is listed without a probe, and an insufficient-scope answer never drops a service. It also and lets `boundary.test.ts` allow exactly the adapter as the importer. The README now describes the implemented seam, how to flip a service, and the removal procedure. - `doc/connections/GOOGLE-WORKSPACE.md`: describes the transport setting. - `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed pins for the changed shared files. ## Verification - `cd server && npx vitest run src/__tests__/google-workspace-rest-transport.test.ts`: 15 tests. They were red before the gateway and discovery changes (10 failed), and green after. With Gmail set to `paperclip_rest` through a test-only change of the map, the tests use the real managed setup, discovery, gateway, policy and screening with a fake Google fetch. They prove: discovery lists the same tool names filtered by scopes after one probe; a read runs with the caller's token and is audited; a draft waits for approval and then runs; a tool outside the grant and a narrowed grant are refused before any Google request; Google's insufficient scope maps to `oauth_insufficient_scope`; a 401 refreshes the token, is not replayed, and the retry uses the new token; an injected email is blocked; a passed deadline aborts the Google request and returns `tool_timeout`; the experimental-feature gate stops calls and discovery; a failed Gmail probe leaves Docs usable and Gmail comes back; a lasting 401 asks for reconnection. A timed-out draft carries the uncertain-write warning in the error, the invocation record and the audit entry on both transports, and an approved REST draft whose request was lost returns the warning. With the default map, a call goes to `gmailmcp.googleapis.com` and the adapter is never called. - `cd server && npx vitest run src/services/google-workspace-rest-dispatch.test.ts src/google-workspace-rest-tools`: eligibility (no partial flip), bearer-only forwarding, signal and fetch pass-through, token outcome mapping, probe, boundary. - `cd packages/shared && npx vitest run src/google-workspace-connectors.test.ts`: every service defaults to `google_mcp`. - Existing Google tests are unchanged and pass: `google-workspace-injection-screening.test.ts`, the Google cases in `tool-gateway-service.test.ts` and `tool-access-service.test.ts` (142 Workspace/Google/Gmail cases). - `npx tsc --noEmit` for `packages/shared` and `server`: clean. - `pnpm verify`: exit 2 (a doc under `doc/` is a global CI input), so required CI supplies broad coverage. - Speed, stubbed fetch, 300 calls after warm-up: the adapter adds about 15 µs per call. A full `gmail__get_message` through `executeTool` took a median of 18.2 ms on REST and 18.3 ms on MCP (p90 21.6 ms and 22.3 ms). The REST path adds no waits, no extra round trips and no dynamic imports. ## Risks - Low risk for production: every service stays on `google_mcp`, and the default-map test proves the adapter is not called. - The server now loads the REST folder at start. It uses only modules the server already loads (MCP SDK, zod). - A later flip must add a probe and the API host for each new REST service. The `Record` type of the probe table makes typecheck fail when a REST service has no probe. - On `paperclip_rest`, MCP resources, MCP Tasks and elicitation do not exist for that service. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code with tool use (shell, file edits, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
d1b5cfe038 |
feat(connections): let users delete data read through a connection (#22010)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents call connected apps, such as Google Workspace, through
Paperclip's tool gateway
> - Paperclip saves part of each tool result, approval previews, app
views and the full run transcripts that contain tool output
> - No user action deleted this data. Removing the connection left it in
place
> - Google's restricted-scope review requires that users can delete the
data an app obtained, and that the privacy policy says how
> - This pull request adds "Delete data read through this connection"
for any connection, on the connection's page and as an option when you
remove it
> - The benefit is that the picker text ("They stay there until you
delete them") is now true, and the privacy policy can link to a help
page
## Linked Issues or Issue Description
**Subsystem affected**
Connections (tool gateway audit tables, run logs, run events) and the
Connectors UI.
**Problem or motivation**
Paperclip stores content from a connection's tool calls in several
places and gives users no way to delete it:
- `tool_invocations.arguments_summary/result_summary` and
`tool_call_events.arguments_summary/request_summary/result_summary` keep
the first ~4,000 characters of each redacted value
(`summarizeToolValue`, `tool-access-policy.ts` `redactArguments`). No
retention limit.
- `tool_action_requests` keeps `canonical_arguments_summary`,
`preview_markdown` and `signed_arguments`. The linked approval card
(`issue_thread_interactions`) keeps copies in `payload.detailsMarkdown`,
`payload.toolAction.previewMarkdown`,
`payload.toolAction.argumentsSummaryJson` and
`result.toolAction.resultSummary`.
- `tool_mcp_app_views` keeps `tool_input` and `tool_result` for MCP app
views.
- Run transcripts hold full tool output: the run log (`local_file` with
an optional S3 mirror, or `s3_segments`/`s3_archive` object journals),
`heartbeat_run_events.message/payload`, and
`heartbeat_runs.stdout_excerpt/stderr_excerpt`. Neither run-log store
had a delete path.
- Connection removal (`removal.ts`) archives the connection and revokes
credentials. It deletes no content.
**Proposed solution**
A durable, resumable, company-scoped deletion request per connection.
See "Design" below.
**Alternatives considered**
- Delete synchronously in the request. Rejected: an interrupted request
leaves partial state that needs a person to retry it.
- Delete only the run events that mention the connection. Rejected: tool
output also reaches the model's later messages, so the safe unit is the
whole run transcript.
- Delete the audit rows. Rejected: counts, outcomes and hashes feed the
activity history and usage counts.
## Design
**Rule.** The job never drops a reference to content it has not
confirmed deleted. It is marked complete, and writes the
`tool_connection.content_deleted` activity entry, only after every step
succeeded. A step that cannot confirm its work throws. The request then
stays pending, the UI says "Paperclip keeps trying until it finishes",
and the worker retries it.
**Store inventory.** Every place that stores tool arguments, results or
previews. I found them from `summarizeToolValue`, `redactArguments`,
`writeAudit`, and every column or JSON field named like summary,
preview, arguments, result, toolInput or toolResult.
| Store | Content | Cleared by this PR | Proof |
| --- | --- | --- | --- |
| `tool_invocations.arguments_summary`, `result_summary`, `progress` |
Redacted request/result preview, provider progress | Yes: `summary`
becomes `""` with `contentDeletedAt`; `progress` null; size and sha256
kept | content-deletion test 1 |
| `tool_call_events.arguments_summary`, `request_summary`,
`result_summary` | Same previews | Yes, same | test 1 |
| `tool_access_audit_events.details.argumentsSummary` (`writeAudit`) |
Argument preview | Yes, same; decision, ids, size, hash kept | test 1 |
| `tool_action_requests.canonical_arguments_summary`,
`preview_markdown`, `signed_arguments` | Approval preview and arguments
| Yes, for settled requests | test 1, card retry test |
| Approval card in `issue_thread_interactions`:
`payload.detailsMarkdown`, `payload.toolAction.previewMarkdown`,
`payload.toolAction.argumentsSummaryJson`,
`result.toolAction.resultSummary` | Approval preview, arguments,
executed result | Yes. Cards are found from every settled request of a
batch, in the same transaction | test 1, card retry test |
| `heartbeat_runs.context_snapshot` and `agent_wakeup_requests.payload`
(`toolAction(s)[].resultSummary`,
`paperclipAgentMessage.untrustedToolResults[].resultSummary`) | Approved
action result delivered to the agent | Yes, for settled runs and settled
wakes | test 1 |
| `tool_mcp_app_views.tool_input`, `tool_result`, `model_context` | App
view input, result, shared context | Yes: rows deleted | test 1 |
| Run log: object journal, archive journal, original `local_file` log
and its legacy S3 mirror | Full transcript | Yes, every copy, for each
settled run that called the connection or received an approved result |
run-log-store tests, test 1 |
| `heartbeat_run_events.message`, `payload` | Transcript events | Yes,
except structural events (lifecycle, terminal, presentation, usage,
compaction, session/turn start, `native.*`) | test 1 |
| `heartbeat_runs.stdout_excerpt`, `stderr_excerpt`, and every string
`summary`, `result`, `message`, `text`, `output`, `content` or `body` at
any depth of `result_json` (including `nativeResult`, `acceptedResult`,
`semanticResult` and their `continuation`) | Output excerpts and final
answer | Yes; schema and control fields kept | test 1, canary |
| `approvals.payload` (formal board approval) | Tool name, risk and
hashes only | Not needed: no content | — |
| `tool_mcp_tasks` | Request hash and sealed provider task id; no result
| Not needed: no content | — |
| `tool_mcp_elicitations.questions` and their question cards | Questions
the provider asked a person | No. These are provider prompts, not tool
results, and the answered question stays in the task. Follow-up if
wanted | — |
| `tool_mcp_skills`, `tool_mcp_skill_files`, `tool_catalog_entries` |
Skills and tool descriptions the provider publishes | No. These are
provider definitions, not data read through tool calls | — |
| Transcripts of later runs that read an app view's `model_context` |
Shared app context | No. Nothing records which runs read it. The help
page says so. Follow-up | — |
| `issue_comments.body`, issue documents (including continuation
summaries), files, chat messages | Task content written by agents or
Paperclip | No, by design. The user removes it by editing or deleting it
or the task. The confirmation says in bold that anything agents wrote
into tasks is not removed, and so does the help page. The canary
excludes `issue_comments.body` by name for this reason | canary asserts
it is kept |
| Raw provider traces | Full provider traffic | No. Admin opt-in,
encrypted, expire within 24 hours | — |
| Feedback exports already sent | Run logs the user chose to share | No.
Already outside Paperclip | — |
| Content of runs of a deleted task or company | Same stores | No.
Follow-up | — |
**Durable request (schema change).** I added one table,
`tool_connection_content_deletions`, and migration `0490`. I followed
`doc/DATABASE.md`: edited the schema, exported it from
`packages/db/src/schema/index.ts`, ran `pnpm db:generate`, and ran the
migration drift and compatibility tests. The classifier marks it
`online_compatible` (a new table and its indexes only). No existing
table can hold a durable per-connection request with a cutoff time,
cursor, counts and retry state. Without it, an interrupted deletion
could resume only when a person pressed the button again.
**Resume after restart.** The worker uses the shared
`registerDeadlineWork` lifecycle on a new
`tool-connection-content-deletion` queue. The request insert signals the
queue in the same transaction. At server start the worker runs once,
`next()` finds any pending row, and processing continues from the saved
phase and cursor. Nobody presses anything. `next()` returns a deadline
only while a pending row exists, so an idle instance sends no recurring
query. A failure records `attempts` and `last_error` and retries after
30 seconds.
**One run selection.** `runsWithStoredContentSql` selects the runs whose
transcripts are deleted: runs that made a tool call or tool-call event
through the connection, and runs whose context lists one of the
connection's approved action requests, limited to runs that still hold a
log, an excerpt, result text or a content event. The dialog count, its
in-progress warning and the job's `runs` phase all use this one
function.
**Phases.** `invocations`, `events`, `auditEvents`, `appViews`,
`deliveredResults` (50 action requests per page; matching runs and wakes
are locked with `FOR UPDATE` before their documents are rewritten),
`runs` (the shared selection, 50 run ids per page, then one run at a
time), `done`.
**Canary test.** `tool-connection-content-deletion-canary.test.ts` puts
a unique marker in a tool call's arguments and result, an approved
action with a preview, a result delivered to a later run and its wake, a
native run that quotes the marker in its answer and events, a run log
migrated from a local file with an S3 mirror to an object journal, an
MCP App view and the audit tables. It checks that the marker is first
present in the database, the object store, the legacy mirror and the log
files. After the deletion it scans every `text`, `varchar`, `json` and
`jsonb` column of every table found through `information_schema` (no
hand-written table list), every object in both stores and every file
under the log directory. Any hit fails with the table and column or the
key. It runs three times: a complete deletion, a deletion interrupted
twice by storage failures and resumed, and two deletions for different
connections on one task at the same time. The only exclusion is
`issue_comments.body`, named with its reason.
**Batching and time budget.** Tool rows are read in pages of 200 with
keyset pagination on the existing `(company_id, created_at)` indexes,
bounded by the request time. Each page's writes and the saved progress
commit in one transaction. Counts are therefore exact, and a crash
repeats at most one page, idempotently. Runs advance one at a time from
the shared selection. Each 1,000-event page is its own step. Log removal
is its own step and runs before its progress transaction, so object
storage calls never run inside a database transaction. The 10-second
budget is checked after every step. Nothing changes on the agent boot or
tool-call path.
**In-flight work.** A run counts as settled only when its status is
terminal, `finished_at` is set, cost accounting is done, and no native
finalization is open. Calls, approvals, events, app views, delivered
results and transcripts tied to other runs or wakes are skipped and
counted. The confirmation says "N runs are still working and will be
skipped. Delete again after they finish."
**Permissions.** Board users with configure access (connection manager
or creator) can delete, like `DELETE /tool-connections/:id`. Agents,
viewers and other companies are refused. The activity entries
`tool_connection.content_deletion_requested` and
`tool_connection.content_deleted` hold counts only.
**UI reads.** The dialog loads counts once when it opens. While a
deletion runs, it polls `GET
/tool-connections/:id/stored-content/deletion`, a single indexed row
read, every 2 seconds. Polling stops when the job completes or the
dialog closes. The Delete button is not gated on counts.
## What Changed
- `packages/db`: new `tool_connection_content_deletions` table and
migration `0490` (online compatible: new table and its indexes only).
- `packages/shared`: `ToolConnectionStoredContent`,
`ToolConnectionContentDeletion` and counts types; optional
`contentDeletedAt` on `ToolRedactedValueSummary`.
- `server`: `RunLogStore.remove`, which deletes every copy of a run's
log (`composeRunLogStore`); `content-deletion.ts` service; deadline
worker wired into startup and pre-drain; `GET
/tool-connections/:id/stored-content`, `POST` and `GET
/tool-connections/:id/stored-content/deletion`, and `DELETE
/tool-connections/:id?deleteStoredContent=true`; OpenAPI entries.
- `ui`: "Delete data" row on the connection's Permissions tab with a
confirmation that shows counts, skipped runs, and "This cannot be
undone"; "Also delete data read through this connection" checkbox in the
Connectors removal dialog.
- Docs: user help
`docs/guides/board-operator/deleting-connection-data.md` (for the
privacy policy link) and an API note in
`doc/connections/CONNECTOR-PLAYBOOK.md`.
- `tests/runner-e2e/source-sdk-public-inputs.json` refreshed for the
shared type change.
`server/src/routes/tool-access.ts` (3,010 lines) and
`ui/src/pages/apps/Browse.tsx` (1,722 lines) grow by about 40 and 20
lines. The routes reuse that file's connection access checks; the dialog
reuses the existing removal confirmation. The new logic lives in its own
files.
## Verification
- `server/src/__tests__/tool-connection-content-deletion.test.ts`
(embedded PostgreSQL): content is gone from every "Yes" store in the
inventory; rows, hashes and sizes stay; another connection and another
company are untouched; a running run is skipped and is deleted after it
settles; a storage failure leaves the request pending with `retrying`,
and the next pass completes it; an approval-card update that fails once
is cleared on the retry; an unrecognised log backend keeps the pointer,
keeps the job pending and writes no completion entry; a zero time budget
yields after every step and still finishes; a repeat request returns the
pending one; agents and outsiders are refused; removal with
`deleteStoredContent=true` queues the deletion.
- `run-log-store.test.ts` and `object-run-log-store.test.ts`: `remove`
deletes local and mirrored logs and object journals, removes a migrated
run's original local file and mirror with its journal, refuses an object
log when object storage is not configured, and is idempotent.
- `ui/.../StoredContentDeletion.test.tsx`: confirmation text, counts,
skipped-run warning, and the request.
- Red: these tests fail on `master` because `remove`, the service and
the routes do not exist. Green on this branch.
- Ran: the tests above, `openapi-routes`,
`server-startup-feedback-export`, `tool-connection-removal`,
`packages/db` migration drift and compatibility tests, all
`ui/src/pages/apps` tests (950), `pnpm check:token-gates`, server and UI
`tsc --noEmit`. `pnpm verify` exits 2 (global CI input changed), so
required CI supplies broad coverage.
## Risks
- Deleting is permanent by design. The confirmation says so.
- A `local_file` log written on another replica's local disk stays on
that pod's disk until the pod is replaced; its S3 mirror is deleted. New
logs on S3-configured instances use object journals, which are deleted.
- On versioned buckets, earlier object versions remain until the
bucket's lifecycle policy removes them (the existing journal delete path
does not remove versions).
- Not in this PR (follow-ups): the "No" rows of the inventory (except
agent-written task content, which is out of scope by design), mainly the
same deletion when a task or a company is deleted, and later runs that
read an app view's shared context.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use and code execution.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
|
||
|
|
55b692d532 |
feat(telemetry): send Cloud server telemetry directly to PostHog (#22006)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The server sends first-party telemetry events through a collector. The collector anonymizes the events and copies them into PostHog. > - Paperclip Cloud is our own service. It needs real IDs (workspace, user, agent, task) so that a person can go from a PostHog event to the exact workspace and task. > - The collector path hashes these IDs. It also cannot link a server event to the browser session that caused it. > - This pull request adds a server-owned direct sender for Cloud only. Self-hosted installs keep the collector path with no change. > - The benefit is real IDs and session links on Cloud, and no change to self-hosted privacy. ## Linked Issues or Issue Description **Subsystem affected** Server telemetry (`packages/shared/src/telemetry`, `server/src/telemetry.ts`). **Problem or motivation** All Cloud telemetry goes through the collector. The collector hashes the install ID, agent IDs and task IDs. So, on Cloud, you cannot find the workspace, user or task of an event. Server events also cannot show in a browser session replay. **Proposed solution** On a Cloud-managed server that has `PAPERCLIP_POSTHOG_PROJECT_TOKEN`, `PAPERCLIP_CLOUD_STACK_ID` and `PAPERCLIP_POSTHOG_ENVIRONMENT`, send each telemetry batch straight to PostHog with `posthog-node`. Use the same event shape that the telemetry backend loader makes today, and add the real IDs. Keep every other install on the collector. **Alternatives considered** Send real IDs through the collector. We did not do this, because the collector exists to anonymize self-hosted data. **Roadmap alignment** This is Cloud analytics infrastructure. It does not change a core product feature. ## What Changed - Add `server/src/services/cloud-posthog-config.ts`. `resolveCloudPostHogConfig()` returns `null` unless the instance is Cloud-managed and has a token and a stack ID. `isPostHogDirectDeliveryEnabled()` also requires an environment and the kill switch on (`PAPERCLIP_POSTHOG_DIRECT` is not `0`). - Add a narrow `TelemetryTransport` seam to `TelemetryClient` in `packages/shared`. With a transport, each flushed batch goes to the transport and never to the collector. Without one, the client does what it did before. A transport can capture per-event context at track time. The context does not go into the collector envelope. - Typed helpers hash `task_id` unless the transport sets `hashesPrivateRefs: false`. Private `source_ref` values (for example a private repository name) are customer content, so they stay hashed on every path, Cloud included, with `source_ref_hashed: true`. - Add `server/src/services/posthog-direct/`: - `event-shape.ts` builds PostHog messages with the loader's event names, metadata keys and key order, the deterministic event uuid formula, and the unknown-enum fallback. It drops events that the backend quarantines (unregistered names). - `enum-fallbacks.generated.ts` holds the backend fallback rules. Enum values come from the shared generated contract. - `transport.ts` loads `posthog-node` with dynamic `import()` only on the first Cloud send. - `request-context.ts` is Cloud-only Express middleware. It reads only `X-POSTHOG-SESSION-ID` and `X-POSTHOG-WINDOW-ID`. It ignores `X-POSTHOG-DISTINCT-ID`. The acting user comes only from the authenticated request actor. Context stops when the response finishes, so later background work does not use that user. - `server/src/telemetry.ts` selects exactly one sender per process. On start, the Cloud sender sends `$groupidentify` (group `workspace`, key = stack ID) and one `cloud.workspace_started` event with `install_hash` (sha256 of the raw install ID). Both go straight to `posthog-node` and are not in `PAPERCLIP_EVENTS`. - `distinct_id` is the acting user ID, else `workspace:<stackId>`. Events without an acting user keep `$process_person_profile: false`. GeoIP stays off on all server events. - Shutdown flushes the client and then shuts down `posthog-node`. - Add `scripts/generate-posthog-direct-fixtures.mjs`. It runs the telemetry backend's own ingest and loader on one envelope and writes the golden fixture and the fallback table. The script header tells how to regenerate them. - Update `packages/shared/src/telemetry/README.md` with a "Cloud Direct Delivery" section about the privacy boundary. - Add `posthog-node@5.38.2` to `server/package.json`. This PR does not change `pnpm-lock.yaml`, because the lockfile refresh workflow owns it. Intended differences from the loader output on Cloud: `distinct_id` (user or workspace, not the HMAC install ID), raw `agent_id`, raw `task_id` (private `source_ref` stays hashed), and these added properties: `stack_id`, `company_id` and `user_id` when known, `environment`, `$groups`, `$session_id` and `$window_id`. The uuid formula is the same. The uuid is different only when the dimensions are different (raw `task_id`). ## Verification - `pnpm verify` returned exit 2 (a global CI input changed: the new script). I ran focused checks. Required CI supplies the broad coverage. - Focused tests pass: `packages/shared` `src/telemetry` (6 files, 42 tests). Server: `posthog-direct-telemetry`, `posthog-direct-event-shape`, `cloud-posthog-config`, `shared-telemetry-events`, `heartbeat-status-preserving-telemetry`, `issue-thread-interactions-telemetry`, `native-run-finalizer-telemetry`, `agent-task-run-telemetry`, `error-handler` (9 files, 115 tests), and `server-startup-feedback-export` (133 tests). - `tsc --noEmit` passes for `packages/shared`, `server` and `cli`. - New tests: - Config matrix: not Cloud, no token, no stack ID, no environment, kill switch, browser and replay flags. - Self-hosted: `posthog-node` is never loaded, the collector gets the batch, and the envelope bytes are the same as before (with `task_id` hashed). Tracing headers are ignored. - Cloud: a private `source_ref` stays hashed and the raw repository name never reaches the sender. - Cloud: one batch goes only to PostHog. Real IDs, `$groups`, `environment` on every event. `cloud.workspace_started` reaches the PostHog sender with `install_hash`. No other event has `install_hash`. - Golden: our builder output equals the backend loader output, except the intended differences above. Key order is the same. - `distinct_id`: user, agent and anonymous requests. A spoofed `X-POSTHOG-DISTINCT-ID` never changes `distinct_id` or `user_id`. A bad session header is dropped. Work after the response ends does not keep the user (red without the response-end guard, green with it). - Kill switch and a missing environment both fall back to the collector. - Local run with a real server and a local capture server (no real PostHog project): - Cloud mode (authenticated, local Postgres, `PAPERCLIP_POSTHOG_HOST` set to the capture server): the capture server got `$groupidentify`, `cloud.workspace_started`, `server.started` and `goal.created` on `/batch/`. `goal.created` from a Cloud tenant user had `distinct_id` = that user, `user_id`, `company_id`, `$session_id`, `$window_id`, `$groups` and no `$process_person_profile`. The spoofed distinct ID header was not used. Nothing went to `/ingest`. `SIGTERM` ran the `telemetry_flush` step and sent the queued events. - Self-hosted mode (same token variables but no Cloud signal): the capture server got only `/ingest` with the normal envelope. Nothing went to `/batch/`. - Runtime dependency note: `posthog-node` loads with dynamic `import()` only on Cloud with direct delivery on. The load happens after startup, outside the boot path. The unit test mocks the package to count loads. The local run used the real package. ## Risks - Medium. This is a telemetry change, so a privacy review is requested. Self-hosted output does not change. The direct path is off unless all three Cloud variables are set, so a merge does nothing until fleet config sets them. - Cloud events with an acting user create PostHog person profiles keyed by the Paperclip user ID. This is intended under the Cloud terms. - The fallback table can drift if the backend adds a new normalization rule. A test fails when a rule does not match the shared enum contract. Enum values come from the shared contract, so new enum values do not drift. - `posthog-node` keeps network failures in its own queue and drops events that PostHog rejects. The client does not resend these, so events are not sent twice. - `pnpm-lock.yaml` is not in this PR. The lockfile refresh workflow adds `posthog-node` after merge. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, local server runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |