Commit Graph
2523 Commits
Author SHA1 Message Date
7ef731ec7e fix(workspaces): name incompatible project storage when a volume-free server refuses a run (#22398)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - A volume-free server admits a run only when its task files have
durable storage.
> - A project can keep its task files in plugin storage, such as an
agent-computers plugin. Only environments of that plugin can use that
storage.
> - A task keeps its selected source when it moves to another project.
So the source project's storage still applies after the move.
> - When an agent in a Daytona sandbox got such a task, the volume-free
check refused the run with a generic message. The message said "native
Paperclip Runner with remote workspace storage". The agent already used
native Paperclip Runner.
> - The run ended `setup_failed`. The task offered Retry, but Retry
always failed the same way. Sentry received the refusal as an unexpected
run failure.
> - This pull request finds the real cause with the existing
project-storage compatibility rule. It records the refusal as a
configuration problem that an owner must repair.
> - The benefit is a message that names the storage and the environment,
a task notice with the correct owner action, and no Sentry noise for
this known configuration state.

## Linked Issues or Issue Description

Related: #17552 (a task project and its selected workspace are separate
settings, so a moved task keeps its source).

**What happened?**

On a volume-free server, a task's source project used plugin storage.
The assigned agent used a sandbox environment that cannot use that
storage. Workspace preparation refused the run with "Volume-free servers
require native Paperclip Runner execution with remote workspace
storage." The run failed with `setup_failed`. The task notice told the
user to press Retry. Each retry failed the same way. Sentry received
each refusal as an unexpected run failure.

**Expected behavior**

The refusal names the real cause: the project's workspace storage does
not support the agent's environment. The run fails
`configuration_incomplete`. The task notice tells the owner to use an
agent in a compatible environment, or a source from a project for this
environment. Sentry does not receive this known configuration state.

**Steps to reproduce**

1. Start the server with `PAPERCLIP_EPHEMERAL_SERVER=true`.
2. Create a project whose storage is a plugin workspace provider.
3. Assign a task in that project to a Paperclip Runner agent in a
Daytona sandbox environment.
4. Wake the agent. The run fails `setup_failed` with the generic
volume-free message.
5. Move the task to a project without plugin storage and comment "try
again". The task keeps its source, and the run fails the same way.

**Paperclip version or commit**

Seen on a hosted volume-free staging server. The new regression test
fails on `master` at 201abacd6e and passes with this change.

## What Changed

- Workspace preparation keeps the volume-free admission rule. When that
rule refuses a run, it checks the task source project's storage provider
against the selected environment with the existing
`assertProjectStorageEnvironment` rule.
- On a mismatch, the run fails with `ConfigurationIncompleteFailure`,
reason `project_storage_environment_incompatible`. The message is the
existing message that names the storage and the environment. The payload
records the provider, the environment, and a stable fingerprint.
- Refusals with any other cause keep the original volume-free error.
- The configuration-incomplete task notice and the recovery next action
name this owner action. Before this change, an unknown reason fell back
to the "missing secret" text.
- Run-failure reporting skips this exact pre-dispatch outcome, like
`ai_connection_required` and `workspace_source_restricted`. A marker
after provider work started, during execution, or without
`configuration_incomplete` is still reported.
- `doc/project-environment-compatibility.md` and
`doc/workspace-storage.md` describe the new outcome.

## Verification

- Red before the fix, green after:
- `server/src/services/heartbeat/workspace-preparation.test.ts` › "names
an incompatible project storage environment when a volume-free server
rejects the run". Before the fix, the run failed with HTTP 422
`ephemeral_execution_configuration_required`. After the fix, it fails
with `configuration_incomplete` and the storage and environment message.
The same test confirms that an unavailable provider keeps the original
error. It also confirms that no workspace is resolved or acquired.
- `server/src/services/__tests__/run-failure-report.test.ts` › "keeps a
run refused for incompatible project workspace storage actionable on the
task". Before the fix, Sentry received the run.
- `server/src/services/recovery/stranded-notice.test.ts` › "names
incompatible project workspace storage instead of a missing secret".
Before the fix, the notice said that a secret was missing.
- Safety cases: three marker variants are still reported (executing
stage, `setup_failed`, provider work started).
- Commands (local, Node 25, embedded Postgres):
- `pnpm --filter @paperclipai/server exec vitest run
src/services/heartbeat/workspace-preparation.test.ts
src/services/__tests__/run-failure-report.test.ts
src/services/recovery/stranded-notice.test.ts` (482 passed)
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/ephemeral-server-contract.test.ts
src/__tests__/project-environments.test.ts
src/__tests__/task-workspace-binding.test.ts
src/__tests__/agent-project-access.test.ts` (passed)
  - `pnpm --filter @paperclipai/server typecheck`

## Risks

- Low risk. The new path runs only after the volume-free rule has
already refused the run, so no run that started before can fail now.
- The only behavior change for those refused runs is the failure code,
the message, the notice, and the Sentry decision.
- One extra plugin-provider read happens only on that refusal path.
- A task that moved projects still keeps its selected source. This
change does not alter that contract. The owner must choose a compatible
agent or a new source.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in a sandboxed workspace.

## 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: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 05:17:37 -08:00
812e30d423 fix(ui): drop Firefox for iOS injected-script errors from browser Sentry (#22378)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The browser UI sends unhandled errors to Sentry through
`ui/src/lib/sentry.ts`
> - Firefox for iOS injects its own Reader-mode and helper scripts into
each page. These scripts read a `__firefox__` global
> - When one of these scripts runs before its setup is complete, the
page's `window.onerror` reports an error. Sentry then records it as a
Paperclip error
> - No Paperclip code defines or reads `__firefox__`. These reports are
browser noise and hide real errors
> - This pull request drops errors whose message contains `__firefox__`
with the built-in Sentry `ignoreErrors` option
> - The benefit is fewer false error reports. All other errors from the
same browser still go to Sentry

## Linked Issues or Issue Description

**What happened?**
Hosted browser Sentry recorded two errors from one page load on Firefox
for iOS: `TypeError: undefined is not an object (evaluating
'window.__firefox__.reader')` and `ReferenceError: Can't find variable:
__firefox__`. Both events have the same trace and the same timestamp.
The only stack frame is the page document (line 1, column 19), not a
Paperclip bundle file.

**Steps to reproduce**
1. Open a Paperclip page in Firefox for iOS.
2. Let the browser's Reader-mode script run before its `__firefox__`
setup is complete.
3. See the `__firefox__` error in the browser Sentry project.

**Expected behavior**
Sentry does not record errors that come from scripts the browser
injects.

**Actual behavior**
Sentry records them as unhandled Paperclip errors.

No duplicate or related public PRs were found (searched for
`__firefox__` and "firefox ios sentry").

## What Changed

- `ui/src/lib/sentry.ts`: add `ignoreErrors: ["__firefox__"]` to the
browser Sentry init options. A module comment tells why.
- `ui/src/lib/sentry.test.ts`: add tests that use the real Sentry SDK.
The tests send both `__firefox__` messages and make sure that Sentry
drops them. Each test also sends a normal app error and makes sure that
Sentry keeps it.
- `doc/observability.md`: describe the filter. Correct an old line that
said that the browser adds no `beforeSend` hook.

## Verification

- `cd ui && pnpm exec vitest run src/lib/sentry.test.ts
src/lib/browser-error-context.test.ts`: 55 passed.
- Without the fix (tests kept), the 3 new tests fail.
- `pnpm verify` was not run locally because of a partial dependency
install. CI runs the full suite.

## Risks

- Low risk. The filter drops only messages that contain the string
`__firefox__`. Paperclip code does not use that name. All other errors
are not changed.

## 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
- [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: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 04:25:06 -08:00
62bc0519d9 fix(native): bound per-turn harness backups by inactivity, not total time (#22382)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - After a remote native turn is accepted, the executor saves the
provider's harness state to durable storage, so another web server can
continue the same conversation.
> - That save runs under a fixed 300 s total deadline
(`AbortSignal.timeout(300_000)`). The deadline covers archive capture,
digest, encryption, the upload, any storage-outage wait and a full
verifying read-back.
> - On staging, five accepted runs failed this save 337–388 s after it
began. The run then reported `native_workspace_sync_out_failed` with
"The operation was aborted" or tar-stream's "already finalized or
destroyed", and workspace copy-back went to retry.
> - #19906 fixed the same fixed-deadline rule on the restore side. The
write side still uses it. Since #20772/#20871 the save also waits out
storage throttling and outages for up to five minutes, which cannot
finish inside a five-minute total.
> - This pull request bounds the upload and the read-back by inactivity
instead of total time. A slow transfer continues while the store makes
progress. A transfer that stops fails with a named code.
> - The benefit is that an accepted turn no longer loses its provider
backup only because the backup is large or the store is slow.

## Linked Issues or Issue Description

Refs #19906 (same idle-deadline rule for failover-backup restores),
#20772 and #20871 (file-source resends and storage-outage waits during
the save), #19108 (stops tar-stream from hiding the real abort), #18932
(durable harness backups).

**What happened?**

On staging, five native per-turn runs failed within one hour, all after
the provider turn was accepted. In each run,
`harness_state.backup.persist` failed after 359,588 / 365,422 / 387,471
/ 383,801 / 337,335 ms, and `session.checkpoint.persist` failed with it.
The only fixed limit on that path is `AbortSignal.timeout(300_000)`
around `persistNativeHarnessBackup` in `native-session-executor.ts`. The
durations sit just above 300 s, plus a variable sandbox sync-out step
before the save. Errors were reported as "The operation was aborted"
and, before #19108, as "already finalized or destroyed".

**Expected behavior**

An accepted turn saves its provider backup while the store keeps making
progress, even when the total time is more than five minutes. A write or
read-back that stalls fails with a named, diagnosable code. A failed
save publishes no backup.

**Steps to reproduce**

1. Persist a native harness backup through a store that takes upload
chunks slowly, so the full save takes longer than the deadline.
2. With the executor's fixed total deadline, the save fails with "The
operation was aborted" and publishes nothing.
3. A store that stops taking bytes, with no caller deadline, waits
indefinitely.

## What Changed

- `native-harness-backup-storage.ts`: generalize
`withDownloadProgressDeadline` into `withTransferProgressDeadline`. It
still wraps `getObject` exactly as before, and it now also wraps
`putFile` with a five-minute idle timer:
- A provider that reads the stream body (local disk) renews it with each
chunk it takes.
- A provider that sends the file source itself (S3 with `sourceFile`,
which never reads the stream) renews it with each request the store
answers, each multipart part it takes, and each resend or outage wait
that starts.
- After the last of them the timer stays armed until the store answers,
so a write that never completes is named too.
- `persistNativeHarnessBackup` gains `transferIdleTimeoutMs` and
`persistMaxMs` (default 30 minutes). The outer bound wraps the whole
save, including the storage-outage wait. With an idle limit, a stalled
upload throws `native_harness_storage_upload_stalled`, a stalled
read-back throws `native_harness_storage_download_stalled`, and the
whole save throws `native_harness_storage_persist_deadline_exceeded` at
the outer bound. Caller cancellation keeps its own reason, and a storage
outage that outlasts its own budget still surfaces as the storage error.
Callers that pass no idle limit (controller archive, offline migration,
preservation) are unchanged.
- `storage/request-stats.ts`: add `observeStorageProgress(onProgress,
work)`, an `AsyncLocalStorage` observer called from the existing
`recordStorageRequest`, `recordStoragePart` and `recordStorageBackoff`
hooks. It is scoped to the wrapped `putFile` call only, and a throwing
observer is ignored. Stats collection is unchanged.
- `native-session-executor.ts`: the per-turn backup passes
`NATIVE_HARNESS_UPLOAD_IDLE_TIMEOUT_MS` (five minutes) instead of
`AbortSignal.timeout(300_000)`.
- Restore behavior and error codes are unchanged:
`withDownloadProgressDeadline` now delegates to the shared helper with
the same defaults.
- `doc/database-backups.md`: document the write-side idle limit, what
counts as progress, and the new codes.

Previous-release story (`rules/upgrade-safe-run-state.mdc`): no
persisted shape changes. Backup rows, references, receipts and
checkpoints are unchanged. A deploy that lands during a save stops the
process, and the pending row is never published, as before.

## Verification

Run from `server/` (provider env vars unset):

- `pnpm exec vitest run
src/services/native-runtime/native-harness-backup-upload-deadline.integration.test.ts`:
6 tests passed. They use embedded PostgreSQL, local-disk storage and an
incompressible 1 MB acpx backup.
- "keeps saving a backup whose upload outlasts the idle window while the
store keeps taking bytes". Under the former fixed-total policy the same
slow upload fails with "The operation was aborted" and publishes
nothing. With the idle limit it completes after more than twice the
window and restores.
- "names an upload that stops taking bytes and publishes no backup",
then saves the same source once the store responds.
- "keeps a file-source upload going while the store answers its
requests, and names one that stops". The fake store never reads the
stream and records each request answer the way the S3 provider does.
- "names a read-back that stops sending bytes and publishes no backup".
  - "stops at the outer bound while an upload still progresses".
  - "lets Stop end a progressing upload with its own reason".
- RED, part 1: with `native-harness-backup-storage.ts` and
`request-stats.ts` reverted to `master`, 4 tests fail. Three stall tests
hang until the 10 s test timeout, and the outer-bound test resolves
instead of rejecting.
- RED, part 2: with only the progress observer disabled, the file-source
test fails with `native_harness_storage_upload_stalled` on an upload
that is still progressing.
- `native-harness-backup-*` suites,
`native-harness-online-preservation`, `src/storage/`,
`storage-request-stats` and `storage-s3-multipart-backoff`: 200 of 201
passed. The one failure, `native-harness-backup-cleanup.test.ts`
("removes retired backups containing immutable skills…", expected mode
256 to be 292), fails the same way on unmodified `master` in this
sandbox.
- `native-session-executor.test.ts`: 1541 of 1542 passed. The new
assertion checks that the per-turn backup passes `transferIdleTimeoutMs`
and no fixed signal, and flipping it fails the `opencode-new-durable*`
cases. The one failure, "compares export process compatibility without
changing conversation identity (changed: false)" (`db.transaction is not
a function`), fails the same way on unmodified `master`.
- `node scripts/typecheck-layers.mjs`: no errors in `server/`. The local
filtered install lacked some CLI/UI/demo packages, which reported
unrelated errors. CI covers the full typecheck.

Not verified: a live staging run with this build. The staging evidence
shows the save failing just after 300 s on several runs. It does not
show which step was slow (upload, read-back or local capture), so the
fix removes the fixed total for every step on that path.

## Risks

- A save that progresses very slowly can now take longer than five
minutes. Before, it failed. The settle step waits for it, up to the
30-minute outer bound.
- A local step that hangs (for example a stalled disk during capture) is
now cut off at 30 minutes instead of 5 minutes, with
`native_harness_storage_persist_deadline_exceeded`.
- For S3 file-source uploads, progress is measured per request, not per
byte. A single request that takes more than five minutes counts as
stalled. For a 16 MiB single PUT, that is a store slower than about 55
KB/s. Multipart parts are 8 MiB, eight in flight.
- If a successor takes over during a long save, the existing fence
checks before and after the upload reject it with `owner_superseded`,
and nothing is published. This is unchanged behavior.

## Model Used

- Provider: Anthropic. Model: Claude Opus 5.5 (`claude-opus-5-5`), with
tool use (shell, file edits) 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: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 03:47:31 -08:00
Devin FoleyandPaperclip c41145e72a fix: wait on pending questions and quiet provider holds (#22363)
## Thinking Path

> - Paperclip manages agents and the tasks they work on.
> - Recovery should continue unfinished work when it is eligible.
> - An active unanswered question is a persisted reason to wait for a
person.
> - Treating a later Retry as an answer makes the recovery sweep
repeatedly request continuations that admission refuses.
> - Provider-limit holds also produce one cancellation toast per task,
even though provider work never started.
> - This PR aligns recovery with persisted interaction status and
presents these waits accurately.

## Linked Issues or Issue Description

Refs: #20466. This addresses the question blocker presentation and
automatic recovery loop; it preserves the existing
interaction-resolution policy.

Related work: #19420 schedules provider quota retries, and #21570
handles notices and reply ownership in agent chats. This change concerns
assigned-task reconciliation, task/inbox status, and per-run
cancellation toasts.

**What happened?**

The assigned-work sweep ignored pending interactions whenever a newer
run carried `explicitUserContinuation`. Continuation admission still
refused the pending question, so repeated sweeps recorded unsuccessful
continuation attempts. The task could meanwhile show an older provider
error as its current blocker. Separately, each pre-dispatch
provider-limit hold generated a cancellation toast, and the one-hour
fallback was described as a known reset and promised start time.

**Expected behavior**

Wait quietly while the question remains active under the shared
interaction eligibility rules, then react to the existing resolution
notification. Dismissed or historical ordinary questions remain
answerable without blocking work; governed requests keep their gates.
Show the current question on task and inbox surfaces. Keep provider
failure history, suppress cancellation toasts for expected provider
holds, and describe scheduled availability checks without promising the
provider will accept work.

**Steps to reproduce**

1. Leave an `ask_user_questions` interaction pending with
`supersedeOnUserComment: false`.
2. Create a later failed/interrupted explicit Retry and run
assigned-work reconciliation repeatedly.
3. Observe that the question remains pending while the sweep attempts
fresh continuations.
4. Separately, let an agent with recent provider rate-limit evidence
receive automatic task wakes without a reported reset time.

## What Changed

- Remove inferred question supersession from both assigned-work fact
loading and candidate selection. Use the existing active-interaction
predicate consistently in those reads, fresh-continuation admission, and
the task projection. Cover dismissed/historical ordinary questions,
retained governed gates, repeated checks, idle workers, and the existing
resolution notification.
- Add the `question` interruption action, load active pending question
IDs alongside approvals in one company-scoped query, and show that
blocker on tasks and inbox rows. Preserve a supported manual Retry after
a failed attempt, suppress duplicate actions for saved input, and keep
other current user gates authoritative. This preserves the existing
issue-detail SQL statement budget. Historical run failures remain
intact. Refresh the shared source SDK input pin.
- Suppress cancellation toasts specifically for cancelled
`provider_limit_wait` runs. Label provider retry deadlines as
availability rechecks, retain relative-time formatting, and record
successful scheduling as an informational lifecycle event.
- Document the wait contract in the continuation architecture guide.

## Verification

- Demonstrated failing regressions before the implementation:
continuation loop, task projection, task notice, cancellation toast,
provider deadline wording, and deadline formatting.
- Initial focused Vitest qualification: 642 tests passed across 14
files, using:

  ```sh
  pnpm exec vitest run \

server/src/__tests__/{assigned-work-invariant,assigned-work-recheck-idle,heartbeat-provider-limit-wait,task-interruption-query}.test.ts
\

server/src/services/{task-interruption-presentation,execution-projection,fresh-continuation-fallback,issue-thread-interactions}.test.ts
\
    server/src/services/recovery/assigned-work-invariant.test.ts \

ui/src/{components/ExecutionBlockerNotice.test.tsx,context/LiveUpdatesProvider.test.ts,context/LiveUpdatesProvider.hook.test.tsx,lib/provider-limit-message.test.ts,pages/Inbox.test.tsx}
  ```
- `pnpm --filter @paperclipai/shared typecheck` — passed.
- Review follow-up: 157 tests passed in `assigned-work-invariant`,
`task-interruption-query`, and `fresh-continuation-fallback`; 575 passed
in `task-interruption-query`, `assigned-work-recheck-idle`,
`task-interruption-presentation`, `issue-question-context`,
`issue-thread-interactions`, and `explicit-native-continuation` (the
query file overlaps). The strengthened final
dismissed/historical/governed projection regression also passed
separately.
- Final query-consolidation verification: 157 tests passed across five
files, including the unchanged 64-statement issue-detail census and
mixed approval/question batches:

  ```sh
  pnpm exec vitest run \

server/src/__tests__/{issue-detail-statements,task-interruption-query,assigned-work-invariant,assigned-work-recheck-idle}.test.ts
\
    server/src/services/task-interruption-presentation.test.ts
  ```
- `pnpm --filter @paperclipai/server typecheck` — passed, including test
layers.
- Manual-recovery follow-up: 204 tests passed across seven
projection/recovery/notice suites, and all 104 Inbox tests passed. The
lost-runner integration still starts exactly one run from a manual Retry
and leaves the question unanswered. The saved-decision census verifies
one decision batch query for a 41-task list, with at most three
statements referencing interactions; the overall 64-statement
issue-detail limit remains unchanged.
- `pnpm --filter @paperclipai/ui typecheck` — passed.
- `pnpm --filter @paperclipai/ui build` — passed.
- `node tests/runner-e2e/source-sdk-public-inputs.mjs $(git rev-parse
HEAD) --check` — passed.
- `pnpm verify` — exit 2: broader CI is required for changed global
inputs. Focused tests and package checks supply local evidence; broad CI
remains required.
- `git diff --check` and a local secret/instance-data scan — passed.
- Final CI on `1c16fe7c0d8`: [trusted CI
workflow](https://github.com/paperclipai/paperclip/actions/runs/44650155842)
passed, including all server shards, native-server verification, build,
canary, e2e, release registry, and serialized suites. All PR checks are
complete, with no failures; the branch is conflict-free.
- Greptile reviewed the latest revision, `1c16fe7c0d8`, at 5/5 with no
actionable findings or unresolved review threads.

The focused tests cover genuine provider failures, live work and
terminal tasks, unchanged task locks/retry delivery, preservation of
historical failures, and question resolution waking the affected task
while other active pending questions remain quiet. Review regressions
also cover dismissed/historical ordinary questions retaining Retry and
governed requests retaining their gates. No live task was retried or
answered for validation.

## Risks

- An active pending question now consistently blocks automatic
assigned-work recovery. Shared interaction eligibility determines when
ordinary conversation input becomes deferred or historical; governed
requests retain their authority. Automatic recovery no longer infers
that a newer Retry resolved an active question.
- Manual Retry keeps its existing admission policy and recovery checks.
The question notice preserves that supported action after a failed
attempt without changing approval or credential authority; pending saved
input prevents duplicate actions.
- The shared interruption action gains `question`; the task and inbox
consumers are updated together. The pending-question query returns only
task IDs and uses the existing company/task/status index.
- Provider cooldown policy, quotas, credentials, routing, cancellation
history, and durable retry timing are unchanged. The actual provider can
still return a rate limit at the recheck.
- No migration is required. Existing large owner modules receive small
localized changes; no code file crosses 1,000 lines.

## Model Used

OpenAI `gpt-6.1-sol` through the Codex harness in T3 Code, xhigh
reasoning effort, with code execution and 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 linked existing issues or described the issue in-PR
following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
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>
2026-11-19 19:54:15 -08:00
DottaandClaude Opus 5.5 25b5cad7f9 fix(native-runtime): start first OpenCode turns from any saved launch-file copy instead of waiting on a stalled one (#22367)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - OpenCode agents in remote sandboxes must have a saved, verified copy
of their launch files before their first turn (#19622, #21287)
> - The first runs of a company share one copy of these files per
server. Other runs wait for it
> - In a restart chaos wave, the shared copy out of one sandbox stalled
for 330 s. Seven other runs waited silently for it. Two runs then failed
before their first turn with the cause `unknown`
> - The copy speed out of a sandbox differs from one sandbox to the
next. When the first copy failed, the other sandboxes copied the same
314 MB in 15 to 24 s
> - This pull request lets every waiting run use the first copy that any
run saves, starts a second copy when the first one is slow, and names
the cause of a stalled copy
> - The benefit is a shorter cold start for the first runs of a company,
no failed run when another run already saved the files, and a named
cause instead of `unknown`

## Linked Issues or Issue Description

Refs #19622
Refs #21287

**What happened?**
A restart chaos wave started 15 OpenCode runs on new Daytona sandboxes
(1 vCPU) in a new company. The first run (A) started the shared copy of
the 314 MB launch files out of its sandbox. The copy did not finish. The
plugin call timed out after 330 s, and run A failed before its first
turn. The other runs waited for that copy without any run event, so the
task looked dead for 284 to 343 s. When run A failed, every waiting run
started its own copy at the same time. Five copies finished in 15 to 24
s. One copy (run B) stalled again and failed after 330 s, although a
saved copy existed after 15 s. One copy (run C) took 5 min and started
its turn 10 min after the run started, although it could have used the
saved copy 5 min earlier. Both failures had the technical cause
`unknown`. Each failure also logged "native result could not be marked
workspace_failed; the reconciliation loop will retry persisted results",
but the run had no result, so there was nothing to retry.

**Expected behavior**
A run uses the first saved copy as soon as one exists. A slow copy does
not hold all first runs. A stalled copy out of the sandbox has a named
cause. A run with no result does not log a result-finalization failure.

**Steps to reproduce**
1. Use a company with remote OpenCode agents on Daytona sandboxes with
durable storage and no saved launch-file copy.
2. Start 8 or more runs together on new sandboxes.
3. Make the copy out of the first sandbox stall (for example, a slow
sandbox link).
4. See that all other runs wait for the full plugin timeout, and see the
failures with the cause `unknown`.

**Agent adapter(s) involved**
OpenCode (native runtime, remote sandbox).

## What Changed

- `shareNativeProviderArtifactCapture`
(`native-provider-artifact-capture.ts`):
- The first capture that saves a ready copy ends the wait for every run.
A run whose own capture is still copying uses the saved copy and aborts
its own copy.
- A run whose own capture fails uses a saved copy when one exists, and
fails only when none exists.
- When the running capture is slower than 90 s, one waiting run starts
one more capture from its own sandbox. At most two captures run at once.
A capture keeps its slot until its copy out of the sandbox ends.
- The start decision is owned by one `SharedArtifactCapture` coordinator
(`tryStart()` returns a release lease).
- When the shared capture fails, one waiting run starts the next
capture. The other runs keep waiting for it. Before, every waiting run
started its own copy at the same time.
- The capture callback now gets its own abort signal, so a superseded
copy stops before upload.
- A failed copy out of the sandbox is now
`NativeProviderArtifactExportError` with the code
`native_provider_artifacts_export_timeout` (plugin call timed out) or
`native_provider_artifacts_export_failed`. The run's technical cause
shows this code instead of `unknown`. A timeout shows "Setting up the
computer took too long ...".
- `runtime-execution.ts`: do not try to mark the workspace as failed on
a native result when the run has no result. Before, this always threw
`native_finalization_missing` and logged a false "will retry" warning.
- `doc/opencode-cold-recovery.md`: describe the new sharing, the second
capture and the new cause codes.

## Verification

- Red/green: with the old `native-provider-artifact-capture.ts`, these 5
new tests fail. With this change, they pass:
- `native-provider-artifact-gate.test.ts`: "starts a run's turn from
another run's saved artifact while its own capture is still copying",
"uses a saved artifact when the run's own capture fails after another
run saved one", "starts one more capture when the shared capture runs
past the hedge delay, not one per waiting run", "does not start a
capture per waiting run when the shared capture fails", "names a stalled
copy out of the sandbox instead of an unknown cause".
- Red/green: `heartbeat-native-predispatch-retry.test.ts` "continues on
a fresh ... sandbox when the provider artifacts fail to save before any
turn" now also asserts that no "could not be marked workspace_failed"
warning is logged. It fails before the `runtime-execution.ts` change and
passes after it.
- `cd server && npx vitest run
src/services/native-runtime/native-provider-artifact-gate.test.ts
src/services/native-runtime/native-provider-artifact-capture-confinement.test.ts
src/services/native-runtime/native-session-executor.test.ts
src/services/native-runtime/native-harness-backup-storage.integration.test.ts
src/services/native-runtime/native-provider-artifact-capture.test.ts
src/services/heartbeat/runtime-execution.test.ts
src/services/task-interruption-presentation.test.ts
src/__tests__/heartbeat-native-predispatch-retry.test.ts`: all pass.
- `npx tsc --noEmit -p server`: pass.

## Risks

- A slow first capture can now cause one more 314 MB copy after 90 s. At
most two copies run at once for one company and manifest. A run whose
saved copy cannot be reused (for example, an ownership fence mismatch)
starts its own copy at once. Before, a failed burst started one copy per
waiting run at once, which was more.
- A superseded copy never uploads, but the provider call that copies
files out of the sandbox continues until it ends or times out. Its local
temporary directory is removed when it ends.
- Sharing is still per server. Two servers can still copy the same
files.
- No change to the rule from #19622: a verified saved copy still exists
before the first turn.
- No runner or image change. No migration.

> 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 (Anthropic), model ID `claude-opus-5-5`, used through Claude
Code with tool use (shell, file edit, test runs). Default context
window; extended reasoning on.

## 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>
2026-11-19 21:11:30 -06:00
19a7381398 feat: restore personal archiving in task views (#22358)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - People use Tasks to see shared work and manage the work that needs
their attention.
> - The old inbox already let each person archive a task and undo that
action.
> - The combined Tasks surface needs the same controls in Unread and in
task table rows.
> - The existing inbox archive rules determine when new activity brings
a task back.
> - This pull request adds an Archived view so people can find and
restore their archived tasks.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Personal task archiving in Tasks. Related work includes the combined
Inbox and Tasks surface (#15100), the Coordinator workspace (#17983),
moving Mine into Tasks (#19363), and the existing inbox archive rules
(#9931).

**Subsystem affected**

Cross-cutting. The UI and task list API reuse the existing inbox archive
state.

**Current behavior**

Mine has an archive action. Unread and the task table have no equivalent
action. The Tasks menu has no dedicated view for restoring archived
tasks.

**Proposed behavior**

Add Archive and Undo to the task views. Let people restore tasks from
Archived. Keep archived tasks available in All tasks.

**Reason and benefit**

People can clear their personal lists and still find the original task.

**Breaking changes**

The task list API adds an optional archive filter and viewer archive
field. Existing callers use the same response and filters unless they
opt in.

## What Changed

- Reuse the current inbox archive and restore actions, activity rules,
and authorization.
- Add Archive and Restore to task table rows, Archive and Undo to
Unread, and a personal Archived view.
- Give each archived task its own Undo control, including when people
archive tasks quickly.
- Add tests for the archive list, account isolation, new activity, row
actions, and Undo.
- Document the archive flow and API filter. Refresh the generated SDK
source input registry.

## Verification

- Passed 287 focused tests in 12 Vitest files. These cover the task
views, row actions, archive cache, and PostgreSQL routes.
- Passed local server and UI typechecks. The source input registry check
also passed.
- Reproduced a missing Undo action when archiving two tasks in a row.
After the fix, the 158 task and inbox tests and the 2 toast tests
passed.
- On macOS with Chrome, archived a task from Mine and restored it using
Undo. Archived another task from All tasks, reloaded Archived, restored
it, and verified its Todo status and return to Mine.
- A human tester also verified Archive, Undo, and Restore in the local
browser.

- On commit `c5526fd9b1`, GitHub's
[verification](https://github.com/paperclipai/paperclip/actions/runs/44630156078/job/135950130662)
and [browser
tests](https://github.com/paperclipai/paperclip/actions/runs/44630156078/job/135946228919)
passed. A targeted retry passed after the first attempt hit a watchdog
self-test failure and two cancelled jobs.
- [Greptile scored
5/5](https://github.com/paperclipai/paperclip/pull/22358#issuecomment-7024083610)
on the same commit. Both review threads are resolved.

## Risks

- An incorrect visibility rule could hide a task from a personal list.
The archived filter uses the same activity predicate as Mine. The
PostgreSQL test covers isolation between people and resurfacing after a
reply.
- The archive state is already stored per person and company. No
database migration is required.

## Model Used

- OpenAI Codex, GPT-6, with shell, code editing, and browser
verification tools. The serving model ID and context size were
unavailable in 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

---------

Co-authored-by: Scott Tong <1504818+scotttong@users.noreply.github.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-19 16:22:07 -08:00
Devin FoleyandPaperclip 24132dac16 fix(tasks): verify PR merges with the managed run identity (#22357)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Native task completion independently verifies that declared PR
deliverables are merged.
> - Runs can already use an authorized managed GitHub connection to
merge private PRs.
> - Completion used the background credential resolver, which cannot
select that run's managed identity.
> - This pull request reuses operation-time identity and grant checks
for completion verification.
> - Agents can finish delivered work while unavailable grants and
unverified merges remain blocked.

## Linked Issues or Issue Description

Related: #22244 introduced the native PR merge gate. No duplicate fix
was found in the open PR search. The roadmap's personal GitHub identity
capability already covers the intended identity model.

**What happened?**

A native agent with a managed GitHub connection merges a private PR,
then completion rejects it as not verified merged. The independent
server-side check only tries legacy company token names or an instance
token; it does not use the agent run's managed connection.

**Expected behavior**

Verify the merge with the run's current accepted GitHub identity,
retaining current grant, membership, trust and company boundaries.
GitHub must confirm the merge regardless of saved work-product metadata.

**Steps to reproduce**

1. Configure a managed GitHub identity with access to a private
repository and no legacy company GitHub token.
2. Use a native task run to merge and register a PR deliverable.
3. Finish the task. Before this change, the merge verifier cannot
authenticate with the managed identity and rejects completion.

## What Changed

- Bind completion credential lookup to the persisted company, native
task and run.
- Add a server-side completion credential path that shares managed
grant, membership and trust checks with command credentials. Both active
and succeeded runs capture identity under the existing task/run locks
and reconcile pending steering acknowledgements before credential
lookup. The command credential API still requires a running run.
- Resolve credentials once for all PRs in a verification attempt; do no
credential work for tasks without PR deliverables.
- Preserve legacy fallback only for runs without a managed identity, and
preserve the public-only restriction on server-environment credentials.
- Add 23 PostgreSQL-backed authorization regression cases and document
completion's identity behavior.

## Verification

- Local checks cover revision
`da2a3608b0375ead646bbbad35af853191488f07`. [Greptile
review](https://github.com/paperclipai/paperclip/pull/22357#issuecomment-7023243798)
is 5/5 on that revision with both prior threads resolved. [Required
CI](https://github.com/paperclipai/paperclip/actions/runs/44625662403)
passed on attempt 2 for the same revision, including typecheck, build,
canary, server/runner suites and all eight e2e shards.
- Red/green: the private-PR and identity-selection cases failed before
the initial fix. Review exposed a succeeded-run reassessment failure and
then an unsettled-steering gap in that path; each has a regression that
failed on the reviewed commit and passes after its correction.
Unresolved steering performs no token lookup, and durable
acknowledgement selects the new person. The full worker test completes
the task after automatic-review withdrawal while command credentials
remain unavailable to the finished run.
- `pnpm exec vitest run
server/src/services/native-runtime/native-pull-request-completion.test.ts
server/src/services/native-runtime/native-completion-feedback.test.ts
server/src/__tests__/github-operation-credentials.test.ts
server/src/__tests__/native-status-reassessment-work.test.ts
server/src/__tests__/run-identity.test.ts
server/src/__tests__/run-identity-projections.test.ts` — 222 tests pass
across six files, on macOS arm64 with Node 25.6.1 and embedded
PostgreSQL.
- `pnpm --filter @paperclipai/server typecheck` — passes.
- `pnpm verify --explain` — exits 2 because the subsystem documentation
selects broad CI coverage. Required CI supplies the broader test/build
coverage; this exit is not a full-suite pass.
- The credential selection, steering, grant and company checks use real
PostgreSQL state. Only the secret vault and GitHub HTTP transport are
mocked; test requests never reach GitHub.
- `git diff --check` and the staged secret/PII scan pass. No runtime
artifacts are committed.
- Earlier CI revision `4e42f64`: the [Build
job](https://github.com/paperclipai/paperclip/actions/runs/44624163145/job/135914203042)
ended after the runner received a shutdown signal and the workflow was
cancelled. Its log does not show a compiler error before interruption;
this interrupted attempt is not build verification. The current revision
subsequently passed its own CI build on attempt 2.
- Current revision canary: the [Canary Dry Run
job](https://github.com/paperclipai/paperclip/actions/runs/44625662403/job/135919504493)
was interrupted by runner shutdown before completion. The repository
runner-loss classifier returns `lost: true` for its actual annotation
and log. A targeted retry was refused while the workflow remained
active. The same revision subsequently passed Canary Dry Run and the
full workflow on attempt 2; the earlier interrupted attempt remains
recorded here separately.
- Live acceptance remains pending deployment; the change has not been
deployed.

## Risks

Completion now reads managed credentials through a server-side path
shared with the existing authorization checks. Successful finished runs
can be reassessed without granting them command execution credentials.
Denied or unavailable identities must remain blocked without falling
through to a different identity; regression tests cover revocation and
company/task isolation. Credential lookup is shared within one bounded
PR verification attempt, not cached across attempts. The existing HTTP
deadline and merge proof requirements remain in place. No migrations or
API contract changes.

## Model Used

OpenAI Codex, `gpt-6.1-sol`, xhigh reasoning, with repository
inspection, code editing and test execution. Context-window size is not
exposed by the 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
- [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>
2026-11-19 14:44:03 -08:00
Nicky LeachandPaperclip 3c32b8d4dc fix(ci): waive lockfile bake time for pinned harnesses (#22349)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner ships pinned harnesses that run those agents.
> - Some new models require a new harness release before they can run.
> - The lockfile bot waits three days before it can merge new dependency
versions automatically.
> - That wait held the Claude and Codex refresh in #22231.
> - This PR waives the wait for a fixed set of harness packages so model
updates can ship as soon as npm confirms the releases.

## Linked Issues or Issue Description

Refs #22231, #22278, #14942, #15572, and #18238.

**What happened?**

The refresh in #22231 held 16 new Claude Agent SDK and Codex versions
even though the new model support needed those harness updates.

**Expected behavior**

Verified npm releases of named harness packages can pass the gate
immediately. The gate applies the normal minimum age to other packages.

**Steps to reproduce**

Compare the parent and head of #22231 across the three lockfiles managed
by the bot. Run the gate with the publish times in its hold comment and
a clock within three days of the releases.

## What Changed

- Exempt 28 exact package names from the minimum age. These cover the
Claude Agent SDK, Codex CLI, their provider-specific ACP bridges,
OpenCode, and the Copilot binaries pinned by Runner.
- Take package identities from the Runner manifest and active provider
profiles, then check the managed lockfiles for platform binaries. Codex
platform aliases use the same registry name with a platform suffix on
each version. Pi and Kimi use separate npm locks. Gemini, Grok, the
local Cursor CLI, and Antigravity use separate install paths. The Cursor
Cloud SDK gets model availability from the service.
- Keep the npm publish-time and resolution checks for every entry.
Update the bot report and setup documentation.

## Verification

- Replayed the exact #22231 lockfile diff using the bot's recorded
publish times and a fixed clock. The previous gate held all 16 versions.
The new gate verified all 16 and held zero.
- Ran the workflow CLI against the same three lockfile pairs and the
live npm registry. It wrote `eligible=true` and reported 16 passing
versions.
- Reconciled the 28 exact names with the Runner manifest, provider
profiles, all three bot-managed pnpm lockfiles, and the npm manifests
for Claude Agent SDK 0.3.328, Codex 0.170.0, and OpenCode 1.18.34.
- Ran `node --test '.github/scripts/tests/*.test.mjs'` locally. All 810
tests passed. The new cases cover mixed refreshes, similar names,
registry errors, missing publish times, and non-registry resolutions.
- Ran `git diff --check`.
- GitHub Actions passed the required typecheck, build, test, and e2e
checks on `9c8bccac51`. The Canary runner shut down on the first
attempt, and browser shard 7 had a test-company cleanup error. Both
passed on the failed-jobs retry. [CI attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44610325309/attempts/2)
- Standard Greptile scored the same revision 5/5.
[Review](https://github.com/paperclipai/paperclip/pull/22349#issuecomment-7021573041)

## Risks

An npm release of an allowlisted harness can reach master during its
first three days through the existing automatic merge path. A
compromised release can use that same path. Every added version still
needs an npm publish time and a registry resolution. Review new platform
package names before adding them to the allowlist. Superagent requests
security review for this policy change. [Scanner
finding](https://github.com/paperclipai/paperclip/pull/22349#discussion_r4634801827)

## Model Used

OpenAI GPT-6 in Codex, with shell and code execution. The exact model
snapshot and context window were not reported.

## 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>
2026-11-19 14:17:32 -08:00
Nicky Leach 28043f8b93 Measure database and projection costs in runtime tool discovery (#22347)
## Thinking Path

> - Paperclip starts agent turns with instructions for the connections
the agent can use.
> - The gateway reads the connected-tool catalog during prompt
preparation.
> - A single discovery span currently covers both database waits and
descriptor construction.
> - Maintainers need to distinguish these costs before changing catalog
reads.
> - This change records the transaction, both queries, availability
checks, and descriptor construction.

## Linked Issues or Issue Description

**Subsystem affected** — Runtime tool discovery and run preparation.

**Problem or motivation** — The existing catalog span cannot explain
time spent before a remote turn starts.

**Proposed solution** — Measure the existing read in place. Record the
number of entries and connections returned.

**Alternatives considered** — A local microbenchmark cannot reproduce a
hosted database or a deployed catalog's sizes. A change to the query
would confound the measurement.

**Roadmap alignment** — This adds diagnostic detail to an existing
operation. Related work includes #14864, which bounded catalog memory
use.

**Additional context** — The PostgreSQL reads share one read-only
snapshot.

## What Changed

- Add a transaction span with children for the entry read and the
matched-connection read.
- Attach the two returned row counts to that transaction.
- Time availability checks and descriptor construction under the
existing catalog discovery span.
- Document which preparation timings can also reach the native run event
table.

## Verification

- Ran the gateway listing-memory, discovery HTTP, and execution timing
context suites with local PostgreSQL. All 30 tests passed.
- Checked the parentage and row counts with a real OpenTelemetry
exporter in memory.
- Ran the standing-instruction integration suite and measured the
catalog from two staging application containers with read-only database
sessions.

## Risks

Each recorded catalog operation adds up to five spans. The existing
per-phase bound applies. Only the OTel transaction span includes the
aggregate row counts. With or without OTel, the existing native
preparation timing path can also persist a run event for each new phase
that takes at least 50 ms, subject to its normal caps. The executor
defers those writes. The database query, tool eligibility, and
authorization contracts stay the same.

## Model Used

OpenAI Codex directed and qualified the work. GPT-6.2 Sol implemented
the instrumentation and regression test.

## 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
2026-11-19 12:41:34 -08:00
806440d12c feat(runner): relaunch a released task as the next run after a restart (#22343)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - An environment plugin can keep a warm task for an agent session.
After each turn, Core releases the task's Runner, and the next run of
the session resumes it
> - #22288 added `resumeIdentityVersion: 1`: for a provider that stops a
released Runner, Core rotates the session to the next run and the
provider starts the Runner again directly as that run
> - Core takes that path only while it still holds the released session
in memory. After a Core restart, it recovers the released task through
the older hand-off: it resumes the task as the previous run, then
switches the Runner's authority to the new run
> - So a provider that advertises the capability still has to keep the
hand-off for every follow-up after a Core restart, and cannot drop it
> - This pull request makes restart recovery take the same path when the
provider advertises the capability
> - The benefit is that a provider with the capability gets one start
shape for a released task, before and after a Core restart, and can
retire the hand-off

## Linked Issues or Issue Description

Follows #22288.

**What existing behavior does this improve?**

The first run of a warm plugin session after a Core restart, when its
task was released and its provider advertises `resumeIdentityVersion:
1`.

**Subsystem affected**

The native session executor and the plugin Runner task owner.

**Current behavior**

After a restart, Core finds the released source on disk
(`inspectRemoteWarmSessionRecovery`), creates a backend that adopts the
task, and calls `recoverSession`. The task owner calls `resume` without
`runner`, the provider starts the Runner as the previous run, and Core
hands it to the new run.

**Proposed behavior**

When the provider advertises the capability, Core recorded the build the
task was released on, the process configuration is unchanged, and the
session is not moving to another task, Core treats the recovery like a
cached released session. It revalidates the recovery, loads the warm
checkpoint, and opens a new backend on the same task with
`relaunchReleased`. A new task owner takes over the submitted task
without adopting a Runner process, prepares the claimant run with the
released source as `priorIdentity`, and calls `resume` with `runner`.
Every other recovery keeps the hand-off.

**Reason and benefit**

A provider that advertises the capability no longer needs the hand-off
for its own tasks, after a restart or not.

## What Changed

- Executor: a remote warm recovery with a released source, a recorded
build, a reusable process configuration and no session move, on a
provider that advertises the capability, revalidates the recovery and
becomes a relaunch: `relaunchReleased` with the released source and
build, the warm checkpoint, and no `remoteWarmRecovery` for the backend.
The startup context ends as for a cached relaunch.
- Executor: the relaunch's task owner can now come from the new backend
(`onPluginTaskOwner`), so the unavailable-reuse fallback and the
rotation revert work without a retained owner. Without an owner, no
relaunch can have started, so the revert applies.
- Backend: a relaunch neither stops a resumed task that has no durable
binding nor resolves a `resumeFrom` task.
- Task owner: an owner created with `relaunch` and the capability takes
over an already submitted task, as an adopting owner does, but adopts no
process: its prepare sends the released source as `priorIdentity`, and
its launcher calls `resume` with `runner`.
- `doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md`: Core prepares the claimant
run before the resume, also after a restart, and a provider must accept
that prepare without state kept in memory.

## Verification

- `server`: `npx vitest run
src/services/native-runtime/plugin-runner-release-resume.integration.test.ts`:
new `adopted restart relaunch` cases for Codex and Claude, with real
runnerd processes. Core restarts while the task is released; the next
run relaunches the task as itself, with no claim, one inspection and no
second submit. The existing `adopted relaunch` case now relaunches both
follow-ups, since the idle close also recovers through this path.
- `server`: `plugin-runner-task.test.ts`: a new owner relaunches without
submitting or adopting, and prepares with the released source; without
the capability it prepares a new task.
- `server`: `plugin-runner-release-resume.integration.test.ts` and
`plugin-runner-eviction.integration.test.ts`: 61 passed.
`native-session-executor.test.ts`: 1535 passed, 7 skipped.
`plugin-runner-task.test.ts`: 118 passed.
- Typecheck: `server` passes.
- Red-green: with the executor lane turned off, both `adopted restart
relaunch` cases fail. Without the task owner change, the new-owner
relaunch test fails.

## Risks

- Only providers that advertise `resumeIdentityVersion: 1` see a change.
Recovery without a recorded build, with a changed process configuration,
or for a session moving to another task keeps the hand-off.
- The provider sees a `prepare` for the claimant run on a released task
right after a Core restart. A provider that tracked unclaimed released
tasks only in memory must handle that prepare (the doc now says so).
- A Core restart in the middle of this path is still not qualified, as
for the cached relaunch.

## 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>
2026-11-19 11:20:48 -08:00
Devin FoleyandPaperclip 46dde54f52 fix(cloud): migrate run evidence during online preparation (#22337)
Drive bounded run-log and provider trace migration pages during online durable-data preparation. Share the page owner and settled-native archive rules with background migration, preserve active-source and storage-integrity guards, and report fresh page results.

Keep canceled transfers owned and tracked until the underlying operation settles. Retain page cursors across the preparation budget.

Verified 52 focused tests, including embedded PostgreSQL and object storage, server typechecking, and all 58 successful PR checks. Greptile 5/5 with no unresolved review comments.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-19 10:28:05 -08:00
Nicky LeachandPaperclip 87ef7097b6 refactor(wake-queue): own blocked admission deferral (#22332)
## Thinking Path

> - Paperclip runs agents in response to work on a task.
> - A person can leave a comment while execution recovery holds that
task.
> - Wake-queue checks the recovery gate under the task lock. Heartbeat
used to choose how to save the blocked input.
> - The deferred-work worker later retries the saved receipt by ID.
> - This change gives wake-queue responsibility for saving the input
before it confirms deferral.

## Linked Issues or Issue Description

**Current behavior**

The gate and the write that makes a blocked wake recoverable have
different owners. Heartbeat also reports an admitted deferral when an
update to an existing receipt matches no row.

**Proposed behavior**

Let the recovery admission operation save the first receipt or update
the existing one in the same transaction. Confirm admission only when
the write succeeds. Keep replaceable automatic signals on their existing
diagnostic path.

**Reason and benefit**

Changes to recovery admission can now be checked against one rule. A
blocked comment must have a durable receipt and remain recoverable
across delivery attempts. Related changes include
[#22292](https://github.com/paperclipai/paperclip/pull/22292) and
[#22290](https://github.com/paperclipai/paperclip/pull/22290).

## What Changed

- Added a transaction-bound deferral operation to wake-queue recovery.
It handles existing receipts, saved input, and replaceable system
signals.
- Scoped retry updates to the company, issue, agent, deferred status,
and receipt ID. A stale receipt cannot confirm admission or cause a new
receipt to be inserted.
- Kept case refusals and issue state callbacks in heartbeat. A saved
comment uses the existing delivery worker and post-commit effects.

## Verification

- Retried a saved comment by receipt ID through the real heartbeat and
run-control entry points. While the hold remained, no run started. After
the hold cleared, repeated retry delivered the comment to exactly one
run.
- Forced a rollback after the wake-queue Postgres adapter saved a
receipt. The test observed the receipt within the transaction and
confirmed its absence after rollback. Tested missing receipts and
receipts for another issue or agent. The admission application test
covers error propagation and post-commit effects when the transaction
fails.
- The test-only revision `9f443f9e6b` passed 9 focused PostgreSQL and
recovery checks and all 15 issue-wake admission application tests.
- The preceding production revision `eb37328472` passed the server
TypeScript check, the module boundary check, and 498 tests across five
queue and recovery suites. Twelve pairs of ordinary comments issued the
same SQL before and after that production change (42 statements for a
fresh wake and 35 for a join).

- Both updated test files passed in full (249 tests). [CI attempt
3](https://github.com/paperclipai/paperclip/actions/runs/44572369812/attempts/3)
passed on `9f443f9e6b` after retrying interrupted jobs. [Standard
Greptile
review](https://github.com/paperclipai/paperclip/pull/22332#issuecomment-7014835241)
scored the same commit 5/5 with no open findings.

## Risks

The affected path handles blocked admissions that may race a retry or a
reassignment. Existing recovery gates, saved comment IDs, receipt
identity, and notifications must survive that race. This change has no
migration or new worker. The healthy admission path is expected to issue
the same SQL.

## Model Used

OpenAI Codex with GPT-6.2 Sol for implementation and verification. Codex
directed and reviewed the change.

## 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>
2026-11-19 10:16:52 -08:00
Devin FoleyandPaperclip 417802ca87 fix(plugins): refresh unchanged-version bundle descriptions (#22295)
Refresh known display descriptions in same-version bundled plugin registrations only when every behavioral field matches. Compare manifests in their persisted JSON form and await bundle reconciliation before final volume-free package qualification.

Verified 77 focused tests, server typechecking, and all 59 successful PR checks. Greptile 5/5 with no unresolved review comments.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-19 09:26:06 -08:00
deacaf727c feat(connections): guided AWS role setup with a per-connection CloudFormation template (#22233)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The AWS connector (#22195) lets agents use AWS with credentials
minted per connection. Its role method stores no AWS keys
> - That method needs the customer to create an IAM role that trusts
exactly one Paperclip connection, but setup only offered the generic
form and a doc
> - The connect API also refused the draft step this method needs, so
the role method could not be set up through the UI at all
> - This pull request adds a guided setup screen. Paperclip saves a
draft, hands the user a prompt for their own agent that creates the
role, takes back the role ARN the agent reports, and tests the same
draft. CloudFormation and IAM steps are there under "Or do it by hand"
> - The benefit is that a person can connect AWS without stored keys and
without typing account details, using a template AWS has validated

## Linked Issues or Issue Description

Refs #22195.

**Subsystem affected**
Connections (AWS connector setup), UI, tool-access API.

**Problem or motivation**
The AWS role method must save a connection before AWS can trust it. The
API rejected `saveDraft` for every method except custom MCP servers, so
the UI could not complete this flow. There was also no screen that
showed the issuer, the subject, the trust policy or a template.

**Proposed solution**
- The connect API accepts `saveDraft` for methods that declare
`credentialMinter`.
- `GET /tool-connections/:id/aws-setup` returns the setup values and a
CloudFormation template generated for that connection.
- A new `AwsRoleSetup` step runs between saving the draft and testing
it. The role is named after the connection and CloudFormation fills in
the account, so the first form no longer asks for a role ARN; the user
pastes it back once the role exists.

**Alternatives considered**
- A one-click CloudFormation quick-create link. Rejected: AWS accepts
quick-create templates only from Amazon S3, so Paperclip would need to
host a public template bucket. The screen offers a download and a
console link instead.
- Instructions in a doc only. Rejected: too many hand-copied values.
- Asking for the role ARN up front. Rejected: the role does not exist
yet, so users had to invent an ARN and then match it exactly.
- Letting the user's agent report the role ARN to Paperclip itself,
through a short-lived link. Not done here: it needs a new
unauthenticated endpoint (and a Paperclip Cloud front-door change). The
user pastes the ARN instead.

## What Changed

- `packages/shared`:
  - The `saveDraft` validation allows methods with minted credentials.
  - New `AwsConnectionSetup` type.
- `server/src/services/connectors/aws/setup.ts` builds the setup values:
  - The issuer, audience and connection subject.
  - The provider host and the trust policy.
- A CloudFormation template with an optional identity provider
(`CreateIdentityProvider`), a role named `paperclip-<connection id>`,
`AccessPolicyArn` (`ReadOnlyAccess` by default for read-only
connections) and `AWSMCPSignInOAuthAccessPolicy`. The account comes from
CloudFormation, so the template needs no edits.
- The service method `getAwsSetup` and the route `GET
/api/tool-connections/{connectionId}/aws-setup`:
  - The route requires `connections:configure`.
  - It returns 422 for a connection that is not an AWS role connection.
- It reports whether the issuer key is published and any role ARN
already saved.
- It returns `available: false` (`address_changed`) when the instance
address changed after the draft was saved, since a role set up for the
old address could never pass the test.
  - It is registered in OpenAPI.
- UI:
- The AWS form no longer shows a Role ARN field (it is hidden with an
empty default).
- `AwsRoleSetup.tsx` shows, by default, only "Set it up with your agent"
(a copyable prompt that checks the AWS account, deploys the template
with `aws cloudformation deploy`, and reports the role ARN) and a field
to paste that ARN. "Or do it by hand" reveals the CloudFormation steps
(download, console link, parameter notes, IAM acknowledgement) and the
IAM console / AWS CLI steps with copyable values; the CLI commands read
the account ID themselves.
- It shows an access-key message when AWS cannot reach the instance, and
asks the user to save again when the instance address changed.
- Failed tests appear in place. AWS error codes show the server's own
plain message, because the shared error copy replaces every 502 with
"temporarily unavailable".
- `useAwsRoleSetupStep` owns the AWS sequence; `ConnectionSetupFlow`
only asks it for request options, hands back results and renders its
step:
- The first Connect for `aws-role` saves a draft and opens the AWS step.
  - "Test connection" resumes the same draft with the pasted role ARN.
- Back keeps the draft, so a later Connect updates it and does not
create a second one. Returning to an unfinished draft reopens the step.
- Docs: the `doc/connections/AWS.md` setup section and the plan's phase
table. The SDK public input pins are refreshed.

## Verification

- `server/src/__tests__/aws-mcp-connector.test.ts` covers a new
API-level case through the real route validation:
- Saving an `aws-role` draft over HTTP works without a role ARN, and
stores the keys the screen uses to reopen it.
- `aws-setup` returns the issuer, subject and the connection's role
name.
- The template's trust condition keys equal `<issuer host>:aud` and
`<issuer host>:sub`.
  - The template provider URL equals the issuer.
- After an address change it returns `address_changed`, and saving the
draft again records the new address.
  - An access-key connection returns 422.
  - No response field looks like a secret.
- `ui/src/features/connections/AwsRoleSetup.test.tsx` covers:
- Only the agent setup shows by default; Test connection stays off until
a valid role ARN is pasted, then sends it.
  - A saved role ARN is filled in.
- The by-hand steps and CLI commands; the agent prompt for read-only and
full access.
  - The template download (filename and object URL cleanup).
  - The unreachable-instance message.
  - The in-place error and the address-changed message.
  - The AWS message mapping.
- `ui/src/pages/apps/AppsConnect.test.tsx` covers the full two-step
flow: the form has no Role ARN field, the first Connect sends
`saveDraft: true` with no role ARN and does not finish, the AWS step
loads the setup, and "Test connection" resumes `aws-draft` with the
pasted role ARN and finishes. A second test reopens the step for a
returning draft.
- Red/green:
  - Removing the API change fails the API test.
  - Removing the draft-first wiring fails the flow test.
- Totals: server AWS, OpenAPI and connector tests (75), shared
`app-definitions` (42), UI connections and apps pages (1108). Typecheck
is clean for shared, server, UI (except Storybook's generated catalog,
which this worktree has not built) and all four server test-tree layers.
- Browser, on a real dev server with an HTTPS public address:
  - AWS appears in Connectors with its logo.
- The form has only region and access level. Connect saves the draft
(reusing an earlier one) and shows only the agent prompt and the role
ARN field; "Or do it by hand" reveals the CloudFormation and IAM steps.
- The copied prompt names the connection's role and stack, and the
template.
- Test connection with a pasted role ARN showed AWS's refusal in place
(no such role, placeholder issuer), as expected. An earlier run found
the generic 502 copy problem, which is fixed and re-checked.
- AWS CloudFormation `validate-template` (dev account, read-only)
accepts the current generated template (role named after the connection)
and reports `CAPABILITY_NAMED_IAM`. The screen tells the user to
acknowledge it.
- Not run: an agent actually running the prompt and creating a stack in
AWS, and Paperclip Cloud staging.

## Risks

- The feature is still behind `enableAwsConnector` (off by default). No
migration.
- The template creates IAM resources in the customer's account, and the
customer must acknowledge that. The role trusts only this connection's
subject.
- If the customer already has an identity provider for the issuer and
leaves `CreateIdentityProvider` at true, AWS fails the stack with a
clear error. The screen explains the parameter.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, the in-app browser against a local dev server, AWS
CLI `validate-template` in the dev account, 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>
2026-11-19 10:53:53 -06:00
Nicky Leach 7ffc58a612 refactor(wake-queue): enforce recovery before task admission (#22292)
## Thinking Path

> - Paperclip admits assignments and task comments while it holds the
task lock.
> - A task can have a recovery hold. An explicit continuation can
authorize additional work.
> - A wake can join an active execution after a provisional check. A
fresh run must settle the continuation in the transaction that creates
the run.
> - Heartbeat previously received both admission functions before either
check ran.
> - Make the wake-queue module release each function after the
corresponding recovery check passes.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Enforce recovery eligibility at the entry points that attach a wake to
an issue execution or create a fresh run.

**Subsystem affected**

Wake-queue and heartbeat issue admission.

**Current behavior**

Heartbeat selects when to read the blocker and apply the explicit
continuation before invoking the admission writers.

**Proposed behavior**

Wake-queue controls access to its two admission writers after the task
is locked. The same recovery and continuation services decide which work
may proceed.

**Additional context**

Depends on #22289. #22290 changes the storage cost of the blocker check
in a separate layer.

## What Changed

- Bind the recovery read to the issue and transaction selected by
wake-queue. Read the current issue lock again after durable chat
authorization when required.
- Expose the busy writer after the preliminary continuation check
passes. Expose the fresh writer after the transaction applies any
required continuation.
- Preserve heartbeat’s existing ordering for system fallback, budget and
daily limits, task retry, and durable receipts.

## Verification

On bde1778161, 420 tests passed across five suites. Server TypeScript
and the module dependency check passed. Final head f9d44c7728 removes
three inline comment lines. All five affected application and locked
PostgreSQL cases passed again on that commit. End-to-end fixture SQL and
lock counts were identical on the parent and the ownership layer. The
application tests exercise blocked recovery, provisional permission
followed by a refusal, and ordinary fresh admission. The PostgreSQL
tests cover current authorization state, scoped writes, rollback, and
deferred delivery.

GitHub selected middle-stack verification. All applicable checks passed
on f9d44c7728. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/44461026141)
· [Standard Greptile review,
5/5](https://github.com/paperclipai/paperclip/pull/22292#issuecomment-6999993272)

## Risks

An explicit continuation can settle a hold. Settling it before the later
gates could lose work if admission declines the wake. The final check
stays immediately before fresh admission in the same transaction.
Heartbeat still owns specialized receipt and fallback paths.

## Model Used

OpenAI GPT-6.2 Sol (gpt-6.2-sol) implemented the change. OpenAI Codex
directed and qualified it.

## 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
2026-11-19 07:23:03 -08:00
Nicky Leach 503268b806 perf(wake-queue): preflight task admission without loading execution context (#22289)
## Thinking Path

> - Paperclip uses task admission to turn assignments and comments into
queued work.
> - Wake-queue owns the issue-admission transaction. Heartbeat
previously loaded full execution context to decide whether a
conversation wake could proceed.
> - After the conversation preflight, task state can change before
admission obtains its lock.
> - Wake-queue now exposes the preflight decision and obtains only the
fields it needs. It provides current task attribution from the locked
row.
> - Heartbeat uses the existing responsible-user and routine rules when
it creates a run.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Admitting board assignments and saved task comments.

**Subsystem affected**

Server task admission.

**Current behavior**

Conversation preflight and fresh-run attribution load full task
execution context from heartbeat, including chat joins.

**Proposed behavior**

Give wake-queue ownership of conversation preflight and its PostgreSQL
read. Use the issue row already locked by wake-queue for fresh-run
attribution.

**Additional context**

Builds on #22280 and #22282. #17396 covers a separate workspace
inspection on task context reads.

## What Changed

- Give heartbeat a preflight decision. Keep storage and the five-field
query inside wake-queue.
- Reuse the conversation and retry predicates for all callers. Keep the
locked recheck after preflight, including durable chat authorization.
- Supply the task's responsible user, parent and routine origin from the
current locked row. A company-only admission supplies no issue.

## Verification

On `b89bed954a`, all 307 tests passed across the wake-queue preflight
and release application suites, heartbeat queue and run-preparation
suites, and Slack conversation lifecycle suite. The integration suites
used embedded PostgreSQL. Coverage includes the owner 403, a
conversation settling before admission locks the issue, saved-comment
attribution after reassignment, and routine ownership written inside the
admission transaction. The layered server typecheck and module
dependency check passed on the same revision.

In a repeated local comparison of base `90d985b8b9` and PR head
`b89bed954a`, we measured 34 samples per revision, scenario, and
recovery-history state, alternating the two revisions in ABBA order.
Server-side admission medians were:

| Recovery history | Assignment | One comment | Two serial comments |
| --- | ---: | ---: | ---: |
| Empty | 23.45 → 21.80 ms | 23.95 → 23.00 ms | 47.30 → 45.40 ms |
| Resolved | 23.35 → 21.30 ms | 23.70 → 22.05 ms | 46.70 → 45.40 ms |

Typical SQL statements fell from 36/37/74 to 35/36/73 for the three
scenarios. Lock statement counts were 2/2/6 for both revisions.
Throughput varied under local contention. These are local measurements.

Standard Greptile scored the exact head 5/5 with no review threads.
[Greptile
review](https://github.com/paperclipai/paperclip/pull/22289#issuecomment-6999578088)

GitHub CI passed on the exact head after one targeted retry of the
serialized server shard. The initial status-card maintenance case timed
out waiting for idle, passed when run locally on the same revision, and
passed in the retried shard. [CI workflow attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44458613437/attempts/2)

## Risks

An early decision can go stale, and the caller must preserve
authenticated actor identity. The locked path retains its own
eligibility checks. A regression exercises the gap between the two
decisions. An attribution test inserts its evidence inside the
transaction to detect a read through a different connection.

## Model Used

OpenAI GPT-6.2 Sol (gpt-6.2-sol) implemented the change. OpenAI Codex
reviewed and qualified it.

## 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
2026-11-19 07:23:02 -08:00
DottaandClaude Opus 5.5 53fedd653b fix(connections): split GitHub Copilot into its own connector (#22238)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Connectors catalog lets people give agents tools and AI
accounts.
> - GitHub showed repository access and GitHub Copilot authentication on
one card.
> - The card had an extra "Connect Copilot" button. Saved Copilot
accounts showed in the GitHub account list.
> - These are two different products. People must find each one by its
own name.
> - This pull request makes GitHub Copilot a separate connector. GitHub
keeps repository and MCP access only.
> - The benefit is a clear catalog. Each card opens its own setup, and
saved accounts show on the correct card.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Discovery and setup of the GitHub and GitHub Copilot connectors.

**Current behavior**

The GitHub card says "Connect GitHub repository access or authenticate
GitHub Copilot agents." It shows a "Connect Copilot" button next to its
own Connect button. Saved Copilot accounts show in the GitHub account
list. Agent connection search returns Copilot as a method of GitHub. The
Copilot setup link that search gives to agents opens the GitHub tool
setup.

**Proposed behavior**

GitHub and GitHub Copilot are two cards. GitHub says "Give agents access
to GitHub repositories, issues, and pull requests." GitHub Copilot has
its own logo and opens Copilot token setup. Saved Copilot accounts,
including accounts saved before this change, show on the GitHub Copilot
card.

**Reason and benefit**

People do not have to know that Copilot is behind the GitHub card. The
catalog names the two products. The Copilot runtime keeps the same
provider identity, token storage, grants, and model discovery.

**Additional context**

This follows the same pattern as the GitHub Code Review Bot split in
#14750. Copilot setup was added in #15705.

## What Changed

- Add a `github-copilot` app definition with the existing
`copilot-token` method. Remove that method from `github`. Restore the
GitHub description and the `developer` category.
- Add the GitHub Octicons Copilot mark (MIT license, from
`primer/octicons`) as light and dark brand assets.
- Map the `github` AI provider to the `github-copilot` catalog entry in
`aiConnectionCatalogSlug`. New Copilot accounts save under a "GitHub
Copilot" application.
- Remove the "Connect Copilot" button from the GitHub card.
- Show saved AI accounts on the card for their provider. This includes
Copilot accounts that were saved under the GitHub application. The
connection page and its reconnect link use the same rule.
- Redirect old `/apps/connect?source=github&method=copilot-token` links
to `source=github-copilot`. Keep the other query values.
- Keep the "My GitHub account" identity wording on the Copilot access
step.
- In connection search and connection requests, file AI accounts under
their catalog entry. Accept the `github` provider for the
`github-copilot` service. Copilot authentication recovery cards now open
GitHub Copilot setup, not GitHub tool setup.
- Keep older Copilot accounts and requests working. An older account
saved under the GitHub application reconnects through GitHub Copilot,
and an older Copilot draft resumes through GitHub Copilot. A recovery
request saved with the `github` service name can complete. A Copilot
request declined before this change stays declined in its continuation.
Adoption accepts the `github` provider binding for a `github-copilot`
request.
- Move the rule that finds an AI account's catalog entry
(`aiConnectionSourceSlug`) into `@paperclipai/shared`, so the UI and
server use one copy.
- Use the Copilot logo for Copilot in the AI account picker and account
details.
- Update the GitHub Copilot connection doc and the GitHub connections
Storybook story. The GitHub and GitHub Copilot setup stories open
**Change** before checking "Connect GitHub as", because that heading
sits in the collapsed access section.

## Verification

- New and updated tests fail on `master` and pass with this change:
  - `pnpm exec vitest run packages/shared/src/app-definitions.test.ts`
- `pnpm exec vitest run ui/src/pages/apps/Browse.test.tsx
ui/src/pages/apps/AppsConnect.test.tsx
ui/src/pages/apps/AppDetail.test.tsx
ui/src/pages/apps/app-connect-policy.test.ts
ui/src/pages/apps/Connections.test.tsx`
- `pnpm exec vitest run
server/src/__tests__/connection-intents-service.test.ts
server/src/__tests__/ai-connections.test.ts`
- `pnpm exec vitest run
ui/src/features/connections/ConnectionSetupFlow.oauth.test.ts`
- Older-account tests cover reconnect, draft resume, completion of a
request saved with `github`, a request declined before the split, and
Copilot adoption. Each test fails without its fix.
- The play functions of all 8 stories in
`github-connections.stories.tsx` pass when rendered with
`composeStories` in jsdom.
- Brand checks: `node scripts/check-app-brand-assets.mjs`,
`ui/src/lib/app-brand-assets.test.ts`, and
`ui/src/pages/apps/AppLogo.brand-assets.test.tsx`.
- Typecheck: `@paperclipai/shared`, `@paperclipai/ui`, and
`@paperclipai/server`.
- Manual check in `pnpm dev:once` with a local company:
1. Open Connectors and search for "GitHub". Two cards show: "GitHub" and
"GitHub Copilot". GitHub has no "Connect Copilot" button.
2. Seed one GitHub tool account and one Copilot account under the GitHub
application, as older installs have them. The GitHub tool account shows
on GitHub. The Copilot account shows on GitHub Copilot.
3. Click Connect on GitHub Copilot. The "Connect GitHub Copilot" page
opens with the Copilot logo and the token field.
4. Open `/apps/connect?source=github&method=copilot-token`. The page
redirects to `source=github-copilot`.
  5. Open GitHub setup. It offers repository access only.
  6. Check the catalog in light and dark themes.

## Risks

- Low risk. There is no database migration. Existing Copilot accounts
keep their application and stored source. The UI and connection search
group them by their AI provider.
- New Copilot accounts save under a new "GitHub Copilot" application and
record `github-copilot` as their source. Code that finds GitHub
repository identities by `sourceTemplateKey === "github"` no longer sees
new Copilot accounts. These are AI accounts, so this is the intended
separation.
- A pending Copilot recovery card from before this change keeps the
`github` service slug. The server still resolves it to GitHub Copilot,
and the card can complete.
- Search for "github" now returns two results: GitHub and GitHub
Copilot.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) through Claude Code, with tool use
(shell, file edits, test runs, and a headless browser for the manual
check).

## 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>
2026-11-19 08:51:36 -06:00
DottaandClaude Opus 5.5 1355f93546 fix(dispatch): schedule a clean loop-limit continuation with its person's work (#22312)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The heartbeat queue decides which queued run an agent starts next.
It puts system recovery in the lowest tier.
> - When a run hits the tool-call loop limit, the server queues a
continuation with the wake reason `issue_continuation_needed`. The
source run succeeded. It did not fail.
> - The queue classed that continuation as system recovery. While any
person-requested run was queued, it got no share. It started only when
the 60-minute aging bound expired.
> - In a restart-chaos wave, 4 of 7 loop continuations waited 60:00 to
60:28. One task broke the "no rest within budget" rule. One run then
resumed an hour-old sandbox, timed out and showed a Retry banner.
> - This pull request schedules a clean loop-limit continuation in the
tier of its task, so a person's task that continues its own work stays
with that person's work.
> - Real failure recovery keeps the recovery tier and the aggregate
share, so a failure loop cannot become high-priority churn.
> - The benefit is that a person's task continues within seconds, not
one hour, and the stale-sandbox Retry path is not reached.

## Linked Issues or Issue Description

Refs #21349

**What happened?**
A continuation queued after the tool-call loop limit waited for the
60-minute aging bound (`QUEUED_RUN_AGING_MS`) on an agent that had
person-requested runs queued. 4 of 7 loop continuations in one
restart-chaos full wave waited 60:00 to 60:28.

**Expected behavior**
A continuation of a person's task whose source run succeeded starts in
the same tier as that person's work. Failure retries stay in the
recovery tier.

**Steps to reproduce**
1. Queue a person's task on an agent with a concurrency limit of 1.
2. Let the run hit the tool-call loop limit, so the server queues an
`issue_continuation_needed` continuation with
`livenessContinuationReason: agent_tool_call_loop`.
3. Keep person-requested runs queued on the same agent.
4. The continuation waits until it is 60 minutes old.

**Paperclip version or commit**
`master` at 70a4351343.

## What Changed

- `queued-run-dispatch-order.ts`: add a `cleanContinuation` dispatch
fact. A clean continuation is not system recovery, so it takes the tier
of its task (person or work) and the normal readiness, priority and age
order. The module stays domain-agnostic: the wake reason is defined once
(`ISSUE_CONTINUATION_NEEDED_WAKE_REASON`, used in
`RECOVERY_WAKE_REASONS`).
- `queued-run-dispatch-order.ts`: one core predicate
(`countsAsRecoveryStart`) drives `isSystemRecoveryRun`, the in-pass
recovery counter, the place-in-line counter and the start-history
counter. Every start with a recovery wake reason that a person did not
ask for still uses up the recovery share. A clean continuation therefore
does not add recovery-reason starts.
- New `queued-run-provenance.ts`: the clean-continuation causes, the
source-run check and `QUEUED_RUN_ORDER_CONTEXT_KEYS`.
- `queue.ts` (`listQueuedRunCandidates`, the real dispatch query) and
`queued-run-line.ts` (the place-in-line query) both read
`QUEUED_RUN_ORDER_CONTEXT_KEYS`, so the dispatcher sees `retryReason`,
`livenessContinuationReason` and `livenessContinuationSourceRunId`.
- `queued-run-line.ts`: set `cleanContinuation` only when all of these
are true:
- the wake reason is `issue_continuation_needed` and
`livenessContinuationReason` is `agent_tool_call_loop`;
- the run has no `retryOfRunId`, `retryReason` or `previousRunId` (it is
not a failure retry);
- the source run (`livenessContinuationSourceRunId`, same company) has
status `succeeded`;
- the source run is not itself a loop continuation, so only the first
hop of a loop chain gets the faster tier.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/services/heartbeat/queued-run-dispatch-order.test.ts
src/services/heartbeat/queued-run-line.test.ts
src/services/execution-projection-agent-queue.test.ts` passes (39
tests), plus `src/services/heartbeat/`,
`queued-run-dispatch-stacking.test.ts` and `recovery-wake-herd.test.ts`.
- Red before the fix, green after it:
- `starts a person's task continuing after the tool-call loop limit with
that person's work, not after the aging bound` (unit; failed with
`expected 'recovery' to be 'person'`)
- `counts a clean continuation's start against system recovery's share,
as the start history does` (unit)
- `starts a person's task continuing after the tool-call loop limit with
that person's work, and keeps failure recovery behind it` (embedded
Postgres; a failure retry, a chained loop continuation and a
continuation of a failed run all stay behind the person's work)
- Assembled heartbeat service
(`src/__tests__/heartbeat-clean-continuation-dispatch.test.ts`, embedded
Postgres, `resumeQueuedRunsForAgent` with one free slot), checks which
queued run actually starts:
- `starts a clean loop-limit continuation of a person's task before a
newer person assignment` (red without the `queue.ts` change, green with
it)
- `starts a newer person assignment before a failure retry of a person's
task` (guard)
- Guard that passes before and after: `keeps a failure retry of a
person's task in the recovery tier while people wait`.
- The `queuedRunDispatchLine` fuzz test now also generates clean
continuations and still matches the dispatcher order for 400 seeds.
- `pnpm verify` ran locally.

## Risks

- Low risk. The change is limited to dispatch order. No schema or API
change.
- A clean continuation can now start ahead of agent work. It is bounded:
one continuation per source run (existing idempotency key), only the
first hop of a loop chain, and only after a succeeded source run. A loop
chain's later hops and all failure retries stay in the recovery tier
with the existing share.
- Recovery-reason starts per hour do not increase. A clean continuation
start uses up recovery's share like before.

> 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 as an agent with tool use (shell, file edit, test runs). Extended
reasoning on.

## 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>
2026-11-19 05:24:53 -06:00
Nicky Leach 1c67687998 feat(runner): start a released Runner again as the next run (#22288) 2026-11-18 23:17:30 -08:00
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>
2026-11-18 20:45:18 -08:00
Nicky LeachandPaperclip f0caee6f95 Use one automatic goal steering decision for task comments (#22277)
## Thinking Path

> - Paperclip can deliver a saved task comment to an agent already
working on a goal.
> - Both posting a comment and editing a task with a comment perform
this decision.
> - Each handler previously checked eligibility, queued the same
command, waited for its result, and decided whether to wake the agent.
> - Separate copies make changes to the fallback rules difficult to
verify.
> - Both routes now call one wake-queue use case for automatic goal
steering.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Automatic goal steering after saving a comment on a task.

**Subsystem affected**

Server task admission.

**Current behavior**

The comment POST and issue PATCH each implement live steering and its
fallback.

**Proposed behavior**

One use case returns whether the current runner acknowledged the
comment. The routes continue through their existing boundary wake logic
when delivery is unavailable or fails.

**Additional context**

Builds on #22276. The explicit board Steer click and automatic goal
steering have separate acknowledgement contracts.

## What Changed

- Keep the assignee, self-comment, and external-conversation guards
together with the active goal decision.
- Preserve the comment-derived command ID, the route's selected agent,
and completion-error reporting.
- Drive both HTTP routes with a single comment through success,
unavailable transport, and rejected completion.

## Verification

On 74e19141dc, both HTTP route suites passed all 158 tests and server
typecheck passed. The initial fixture crossed the test file size limit.
The final revision shares one existing service mock across Vitest resets
and reduces the file to 974 lines. Eight table-driven cases cover each
route with one comment and an acknowledged, rejected, timed-out or
unavailable live command.

Run `pnpm exec vitest run
server/src/__tests__/issue-update-comment-wakeup-routes.test.ts
server/src/__tests__/issue-comment-reopen-routes.test.ts`, `pnpm
--filter @paperclipai/server typecheck`, and `node
scripts/check-module-boundaries.mjs`.

## Risks

Returning success too early would suppress the task wake and lose the
comment as input. A confirmed delivery must suppress the duplicate wake.
Both routes exercise these outcomes.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:41 -08:00
Nicky LeachandPaperclip 8af66f48e9 Admit explicit queued steering with durable acknowledgement in wake-queue (#22276)
## Thinking Path

> - A board user can send a queued message into an active agent turn.
> - The server must know which queue, issue and run the user selected.
> - A provider can accept a message even when the client loses the HTTP
response.
> - The route previously handled authorization, replay, delivery,
database writes and response construction in one block.
> - Wake-queue can own the steering operation and its acknowledgement
while the route keeps the board access decision.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Explicit same-turn delivery of a queued board comment or interaction.

**Subsystem affected**

Server task admission.

**Current behavior**

The issue route issues SQL, interprets the provider acknowledgement and
updates the wake, run and identity.

**Proposed behavior**

The route calls one steering command. The command decides replay, checks
the revision and the selected entry, and leaves an uncertain delivery
pending. The adapter handles identity reservation, the issue and wake
locks, and persistence after acknowledgement.

**Additional context**

Builds on the board queue extraction. Related earlier work in #13160
locked the target run while waiting for a provider. Today's runner
writes its acknowledgement to that row.

## What Changed

- Use the shared board queue read and lock for pending messages and
acknowledgement replay.
- Keep the target run available while waiting for the provider. Re-read
and lock the scoped run after acknowledgement and preserve concurrent
result updates.
- Leave HTTP access, activity logging, response redaction and error
translation with the route.

## Verification

On a3d18b1b66, the full route and mutation suites passed 162 tests
together with the repository Postgres runner. An independent route-only
run passed all 145 assertions and timed out cleaning up the database.
Eleven focused checks passed, including the final interrupt audit
assertion. Server typecheck and module boundaries passed.

Run the queued-comment route suite and the wake-queue application tests.
Exercise exact replay, concurrent acknowledgement writes, stopped
targets, fresh-session approvals, permission checks, definite rejection
and an uncertain timeout.

## Risks

A wrong acknowledgement decision could consume a message twice or drop
an undelivered message. The transaction checks the company, issue, agent
and run and merges the latest result before consuming the queue entry.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:40 -08:00
Nicky LeachandPaperclip ebb98120dc Own the issue admission lock and dispatch after commit in wake-queue (#22272)
## Thinking Path

> - Paperclip admits work for a task while other agents and users may
also act on it.
> - A fresh run and a wake behind an active execution both require the
same issue lock.
> - Heartbeat previously opened that transaction and passed handles
across the module boundary.
> - The wake-queue module can bind both admission operations to the
locked company and issue.
> - The result of the database commit determines whether to emit a
queued event, dispatch a run, or return a saved result.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The transaction and handoff used by task-bound wake admission.

**Subsystem affected**

Server task admission.

**Current behavior**

Heartbeat opens the transaction, builds a scope for the busy path, and
dispatches based on the result. Its contention handler can reach
buffered side effects after a rollback.

**Proposed behavior**

Wake-queue owns the lock and the durable acknowledgement. The
application hands off a committed result. A rolled-back contention
attempt returns without publishing its buffered effects.

**Additional context**

Depends on #22268 and #22266.

## What Changed

- Bind the busy and fresh admission operations to a single company and
issue in Postgres. Remove the transaction scope object.
- Keep specialized heartbeat gates and continuation writes on the
acquired transaction.
- Buffer the workspace preflight activity publication until the
transaction commits.
- Centralize the handoff for new, coalesced, replayed, deferred, skipped
and durable results.

## Verification

On 1c5a069406, local qualification passed 94 application tests, 33
focused Postgres scenarios, and all four fresh/busy rollback cases.
Server typecheck and the module boundary check passed.

Run the wake-queue application and adapter tests and the heartbeat queue
and comment wake suites. Verify the rollback, replay, chat
acknowledgement, and tenant and issue mismatch cases. Run the server
typecheck and module boundary check.

## Risks

The ordering of commit, saved notification and dispatch is observable. A
recognized chat authorization contention now discards buffered effects
from the rolled-back transaction. Specialized heartbeat policy still
uses the locked database transaction.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:40 -08:00
Nicky LeachandPaperclip eca7f85778 Admit saved task comments with the fresh issue run (#22268)
## Thinking Path

> - Paperclip agents take work from assigned tasks and from user
comments.
> - A fresh task run can include saved comments when the current agent
or a confirmed former assignee owns them.
> - Connected chat messages and resolved interactions have separate
authority and session requirements.
> - Heartbeat previously decided which receipts to adopt between the
three calls that saved a new run.
> - One wake-queue use case now selects the receipts and commits the
same run and comment lineage.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Assignment and comment continuation when a task needs a fresh run.

**Subsystem affected**

Server task admission.

**Current behavior**

Heartbeat chooses the comment receipts to consume, reads their source,
and builds the final run context.

**Proposed behavior**

One application operation admits the run. Its Postgres adapter loads
eligible company and agent receipts under the issue lock. The caller
supplies the responsible user and records the specialized continuation.

**Additional context**

Builds on #22266. The existing release and queued-comment boundaries are
in #13136 and #13145.

## What Changed

- Keep exact resumed receipts separate from ordinary board comments.
Adopt a prior assignee’s comments only when the interrupted run proves a
handoff.
- Use the same canonical comment ID codecs for admission and dispatch.
- Test the assignment path with one or two saved comments and
independent chat and interaction receipts.

## Verification

On c957f8529c, 260 tests passed across the four admission, liveness and
responsible-user suites. The saved Grok interrupt route passed its
exactly-once continuation test. A separate Postgres run passed the
ordered comment and rollback checks, both reassignment cases, and the
company isolation test. Server typecheck and module boundaries passed.

Check the fresh admission and handoff cases in
`server/src/services/heartbeat/queue.test.ts`. Run `pnpm exec vitest run
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/services/issue-queued-comment-queue.test.ts`, `pnpm --filter
@paperclipai/server typecheck`, and `node
scripts/check-module-boundaries.mjs`.

## Risks

Receipt selection controls which user input reaches the next agent. The
store requires the same company, issue and executor or a verified
handoff. Chat and interaction receipts preserve their independent
delivery.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:39 -08:00
Nicky LeachandPaperclip f324238f73 Move fresh issue run and receipt writes into wake-queue (#22266)
## Thinking Path

> - Paperclip manages AI agents at work.
> - Assigning a task or resuming it from a comment can create a queued
run.
> - The wake-queue module handles admission behind an active execution.
Heartbeat also writes the receipt and run when a new execution is
needed.
> - These writes share the issue lock. Splitting them across
transactions would allow duplicate or partially bound work.
> - This change puts the fresh writes in the wake-queue module under the
existing lock.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Creating a queued run for an assigned or continued task.

**Subsystem affected**

Server task admission.

**Current behavior**

Heartbeat constructs the receipt and run, handles retry lineage, and
ties adopted receipts to the run.

**Proposed behavior**

Wake-queue owns receipt promotion, fresh-run construction, and receipt
binding. Heartbeat still selects saved comments and orders recovery
effects inside the same transaction.

**Additional context**

Earlier module boundaries were introduced in #13136 and #13145.

## What Changed

- Move fresh receipt, run, and binding writes to a transaction-bound
Postgres adapter.
- Keep explicit continuation and reconciled retry lineage in the
application layer.
- Scope receipt updates by company and durable promotion by agent. Cover
both predicates with a database test.

## Verification

On commit 7479acbd22, all 104 heartbeat queue tests passed using the
repository Postgres command runner. All 297 assertions passed in the
six-file sweep. The standalone cluster cleanup timeout also reproduced
on pristine base 92dbf39e6f after all 103 base tests passed.

`node cli/node_modules/tsx/dist/cli.mjs
packages/db/src/test-postgres-command.ts -- node
node_modules/vitest/vitest.mjs run
server/src/services/heartbeat/queue.test.ts`

Run `pnpm exec vitest run server/src/services/heartbeat/queue.test.ts
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts`. Run
`pnpm --filter @paperclipai/server typecheck` and `node
scripts/check-module-boundaries.mjs`.

## Risks

Changing write order can attach the wrong receipt or lose retry lineage.
The caller retains the transaction and the interleaved chat and recovery
effects. This is a structural change. No latency improvement is claimed.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:39 -08:00
Devin FoleyandPaperclip 3dffb2c9dd Fix project sidebar navigation and pinned task expansion (#22264)
Open recent and pinned projects on Tasks and share their expandable task list.
Keep project pin and reorder controls at the header. Preserve unread markers
and monitoring status through the existing full issue response.

Verified 82 focused tests, UI typecheck, production build, token gates,
and 58 successful CI checks. Greptile is 5/5 with all threads resolved.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-18 17:38:38 -08:00
DottaandClaude Opus 5.5 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>
2026-11-18 18:44:45 -06:00
Devin FoleyandPaperclip 75ae377438 feat(ui): offer to cancel active subtasks (#22228)
Offer to cancel readable active subtasks when a task is canceled. Show a counted heading, status icons and titles, with choices to cancel only the parent or also its listed subtasks. Include waiting chat descendants and skip terminal or moved tasks observed before each write.

Verified with focused UI and database tests, final CI, Greptile 5/5 with no unresolved comments, and manual acceptance.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-18 16:41:06 -08:00
DottaandClaude Opus 5.5 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>
2026-11-18 18:24:03 -06:00
Devin FoleyandPaperclip d4b7ae5532 fix(tasks): require merged PR deliverables before native completion (#22244)
Keep native tasks with declared pull request deliverables active until
GitHub verifies every deliverable is merged. Preserve delivery guidance
in follow-up contracts and recheck the current outputs under task locks.

Use bounded incomplete-work feedback during reassessment, including for
saved non-Done reports. Serialize work-product restoration and identity
changes with completion. Preserve configured reviews and conversations.

Add regression coverage and repair the CI fixtures exposed during
qualification. All CI checks pass on afee630120. Greptile is 5/5 with no
unresolved review threads.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-18 16:20:17 -08:00
673742bfc6 fix(ui): keep artifact previews in agent chat (#22252)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent Chat lets people discuss work and review the plans and
documents it produces.
> - A document link in Chat promises to open the sidebar. It currently
moves the reader to Tasks.
> - Readers need to see the document and the conversation together, even
when the window is narrow.
> - This pull request opens the document in Chat, frees space for
reading, and gives readers a link to the source task.
> - Readers can review the saved revision in context and open the task
when they need its details.

## Linked Issues or Issue Description

Refs #11226 for the document sidebar that this change builds on.

**What happened?**

Opening a saved plan from Agent Chat changed the route to Tasks. The
document could show the same title twice. At narrow desktop widths, the
chat list left too little space for the conversation beside the
document. A task opened by UUID could still show a Chat header.

**Expected behavior**

The sidebar shows the saved revision beside the current conversation. It
shows a matching title once. The chat list collapses when space is
tight. The source link opens the standard task header with status, name,
and ID.

**Steps to reproduce**

1. Open an Agent Chat with a saved plan and select its sidebar link.
2. Use a narrow desktop window and inspect the conversation and plan.
3. Open the task that owns the plan and inspect the breadcrumb.

**Paperclip version or commit**

Reproduced on source commit `8285a81280`.

**Deployment mode**

Local trusted development instance with synthetic data.

## What Changed

- Open sidebar document links on the current Chat route. Keep the
requested revision and document owner, including links inside another
task’s preview. Provide an **Open source task** link.
- Show one title when the document title matches the opening Markdown
heading.
- Collapse the desktop chat list when an artifact tab would leave less
than 420 px for the conversation. Keep **Browse chats** in the header
with access to saved chat history. Restore the list when there is room.
- Use the task breadcrumb on task URLs, with the short UUID for a
conversation-backed task without a number.

## Verification

- Ran 618 focused Vitest tests across 18 UI files on the published
revision `2ff6c9e931`. All passed.
- Ran `pnpm --filter @paperclipai/ui typecheck`. It passed.
- Checked the synthetic demo in Chromium. Opened the plan in Chat,
checked the title, resized the window, and followed **Open source task**
to check its breadcrumb. Also verified a link inside a preview owned by
another task.
- Reproduced the chat navigation failure from the CI trace. The same
Playwright test passed locally after limiting collapse to artifact tabs.
- GitHub CI passed on `2ff6c9e931`, including build, typecheck, and all
browser shards. The remaining jobs passed on a retry after runner
shutdowns and a server handover test failure. The handover suite also
passed locally (19 tests). [GitHub
CI](https://github.com/paperclipai/paperclip/actions/runs/44423540581/attempts/2)
- `pnpm verify` selected broader CI coverage because `doc/PRODUCT.md`
changed. The full local suite was not run.

## Risks

The chat list changes visibility when an artifact tab is active and the
available width crosses the threshold. The list stays mounted to keep
its search text. Document tabs use the existing read API and check the
owning company. This change adds no database migration or API contract
change.

## Model Used

OpenAI Codex (GPT-6), with repository tools, shell execution, 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 linked existing issues or described the issue in-PR
following the relevant issue template
- [x] I have used public GitHub references for linked work
- [x] My branch name describes the change and contains no internal
Paperclip ticket ID
- [x] I have run focused 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>
2026-11-18 16:19:13 -08:00
DottaandClaude Opus 5.5 11d777b80f feat(server): fit PostHog proxy limits to busy Cloud stacks and make them configurable (#22243)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - On Paperclip Cloud, the board UI sends browser analytics to PostHog
through a same-origin proxy at `/_ph`
> - The proxy limits requests in flight: 16 per client address and 256
in total
> - Each open tab runs posthog-js, and one tab can have a few requests
in flight at once
> - On Railway without `TRUST_PROXY`, `req.ip` is the private edge hop,
so all visitors share one 16-request limit
> - This pull request raises the limits, makes them configurable, and
stops the per-client limit when `req.ip` is a shared private hop
> - The benefit is that busy stacks with many users and many tabs do not
lose analytics to 429 answers, and ops can see when a limit is hit

## Linked Issues or Issue Description

**Subsystem affected**
Server: the PostHog reverse proxy for Cloud browser analytics
(`server/src/routes/posthog-proxy.ts`).

**Problem or motivation**
The proxy limits are too low for busy Cloud stacks. One user with many
tabs can use 16 requests in flight. Behind the Railway edge without
`TRUST_PROXY`, `req.ip` is a private `100.64.x.x` hop, so all visitors
share one 16-request limit. The proxy then answers 429 and posthog-js
drops or delays events and replay uploads. Ops cannot change the limits
and cannot see when the proxy refuses requests.

**Proposed solution**
Raise the defaults to 128 per public client address and 1024 in total.
Read both limits from two environment variables with a strict parse and
a ceiling. When `req.ip` is not a public address, apply only the total
limit. Give each request a 60 second deadline. Log a warning at most
once a minute when the proxy refuses requests at a limit.

**Alternatives considered**
Find the visitor for the per-client limit from `X-Forwarded-For`. A
client can write that header, and an earlier security review asked the
proxy to keep `req.ip` as the key, so this change does not do that.
Scale the per-client limit for a shared hop. All visitors share the hop,
so a scaled limit is only a second total limit. The proxy applies the
total limit alone instead.

**Additional context**
Fleet operators can set the variables with an `env_config` campaign.
`doc/cloud-browser-analytics.md` tells how. Refs #22012 (the proxy) and
#22052 (visitor address behind a private hop).

## What Changed

- Raised `DEFAULT_POSTHOG_PROXY_LIMITS` to 128 requests in flight per
client address and 1024 in total. The 64 MiB body limit did not change.
- Added `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` and
`PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT`.
`resolvePostHogProxyLimits` reads them where `resolvePostHogProxyMount`
builds the proxy. A value must be a whole number from 1 to 65536. An
invalid value logs a warning and uses the default. The server does not
stop.
- Added `posthogProxyClientKey`. It returns `req.ip` only when it is a
public address. For a private, carrier-grade NAT, loopback, link-local
or other reserved address, or no address, the proxy applies only the
total limit. The key never comes from a client header.
- Added `createPostHogProxyLimitReporter`. When the proxy answers 429,
it logs `PostHog proxy refused requests at its in-flight limit` at most
once a minute. The fields are the refusal counts per limit since the
last warning, the requests in flight, the limits and the time since the
last warning. The warning has no addresses. It uses no timer: it checks
the time when a refusal occurs.
- Added a request deadline of 60 seconds from the time the proxy accepts
a request. At the deadline, the proxy stops the request to PostHog and
closes the browser response, also when PostHog already finished and the
browser does not read the response. The slot is then free again. Before,
the 30 second upstream timeout was an idle timeout, so a slow body that
sent a byte at a time could hold a slot until the server request timeout
(300 seconds).
- The mount object now also returns the limits in use.
- Updated `doc/cloud-browser-analytics.md`: the limits, why these
defaults, the variables, the shared-hop behavior, the warning fields and
how to tune a fleet with an `env_config` campaign.

Why these defaults:

- 128 per address covers about 10 people behind one office network, each
with 4 tabs and 3 requests in flight per tab, with space left over.
- 1024 in total keeps memory bounded. The proxy streams bodies, so a
request holds two sockets and the stream buffers between them, not the
full body. In a local test on this branch, 1024 held requests added
about 96 MiB of resident memory with 4 KiB bodies and about 173 MiB with
256 KiB bodies (256 held requests with 4 KiB bodies: about 40 MiB).
These numbers include the test client and the test upstream in the same
process, so the proxy share is smaller. Operators can lower the limit
for small stacks.

## Verification

- `cd server && npx vitest run
src/__tests__/cloud-posthog-browser.test.ts`: 87 tests pass (5 runs in a
row).
- New tests:
- Defaults, values from the environment, an empty value, and invalid
values (`0`, `-5`, `1.5`, `1e3`, `12abc`, `abc`, `0x10`, `+8`, `65537`,
`1024000`, a value larger than a safe integer). `65536` is accepted.
Each invalid value keeps the default and warns once per variable.
  - The mount passes the configured limits to the proxy.
- Per-client limit for a public address (with `trust proxy` set): a
second request from the same address gets 429, a request from another
address gets 200.
- Shared private hop (no trusted proxy, peer is loopback): the
per-client limit does not apply, and the total limit still answers 429.
- A forged `X-Forwarded-For` does not select the bucket when no proxy is
trusted: three held requests with the same forged public address and a
per-client limit of 1 all get 200.
- Request deadline: an upstream that does not answer gives 502 at the
deadline and frees the slot, a body that trickles in is cut off at the
deadline, and a 16 MiB response that the browser does not read is closed
at the deadline.
- The tests wait until the held upstream receives each request, not for
a fixed time.
- Total limit across public addresses, and the reported reason (`total`
or `per_client`) for each 429.
- The warning rate limit: one warning for the first refusal, none in the
next 60 seconds, then one warning with the counts of the refusals in
between, and no addresses in any warning.
- Red/green: with the shared-hop rule removed (`posthogProxyClientKey`
returns `req.ip`), 9 of the new tests fail. With the deadline removed,
the 2 deadline tests fail. With both, all pass.
- `cd server && npx tsc --noEmit -p tsconfig.json`: passes.
- `pnpm verify`: exit 2, because `doc/cloud-browser-analytics.md` is a
global CI input. Required CI supplies the broad coverage.
- Memory numbers come from a local script that held 1024 requests
through the proxy against a local upstream (Node 26, macOS).

## Risks

- Higher limits let more requests use memory and sockets at once. The
worst case is bounded by the total limit, and operators can lower it
with `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT`.
- Behind a shared private hop, one client can use all of the total
limit, and other visitors then get 429. The request deadline frees each
slot after at most 60 seconds, but a client that sends again can keep
the limit full. Before this change, the same visitors shared a limit of
16, which one client could also fill. A separate limit for the hop would
not help the visitors behind it, because one client that fills it blocks
all of them. Setting `TRUST_PROXY` brings back the per-client limit.
- A PostHog request that takes longer than 60 seconds now fails with
502. posthog-js bodies are small and PostHog answers in well under a
second, so this does not affect normal traffic.
- If an operator sets `TRUST_PROXY` to trust every hop, `req.ip` comes
from the client's `X-Forwarded-For`. This was already true before this
change. The total limit still applies.
- The proxy is mounted only on Cloud with browser analytics on.
Self-hosted installs do not 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 (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>
2026-11-18 18:05:52 -06:00
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>
2026-11-18 16:04:42 -08:00
DottaandPaperclip 3f263e4faf feat(ui): align routine controls and remember list views (#22182)
## Thinking Path

> - Paperclip helps people manage AI agents and their work.
> - Routines define recurring work and create tasks.
> - People need the same controls to find and inspect routines as they
use for tasks.
> - The routine list had different search controls and no detailed
filters or column choices.
> - This pull request aligns the controls and remembers each person's
view.
> - People can share a filtered link and see the responsible person
beside the agent.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The Routines list controls and metadata in the current and classic
interfaces.

**Subsystem affected**

ui/ — the React board.

**Current behavior**

Routines use different search controls from Tasks. The list has limited
view settings and no filters for project, agent, enabled state,
responsible person, or source. Routine metadata is fixed.

**Proposed behavior**

Show New routine on the left. Show Search, Sort, Filter, Group, Columns,
and View all tasks on the right, in that order. Use the shared Tasks
search and filter controls. Show the responsible person next to the
agent. Let people choose metadata columns. Save filters, search, sort,
and grouping in the URL. Remember view settings per person and company
in local storage. Use a play icon for manual runs.

**Reason and benefit**

People can scan routine ownership, find a subset, share its link, and
return to their preferred columns and view.

**Breaking changes**

The list uses metadata columns with horizontal scrolling on narrow
screens. Existing company-level sort and group preferences are read as a
fallback. No API or database change is required.

Related work: Refs #22009, Refs #18606, Refs #18317. The open PR search
found no duplicate of this list-control change. ROADMAP.md lists
Routines as shipped and has no overlapping control work.

## What Changed

- Align both Routines toolbars with the requested order and shared
search and button styles.
- Extract the existing Tasks filter group and checkbox row for reuse by
Routines.
- Add project, agent, enabled, responsible person, and source filters.
- Keep linked filters ahead of saved filters. Preserve unrelated URL
parameters.
- Save preferences per person and company. Keep the controls usable when
storage is unavailable.
- Add selectable Project, Agent, Responsible user, Last run, and Enabled
columns.
- Use play-only manual run buttons with accessible names and pending
indicators.
- Correct the empty message when a status filter excludes every routine.
- Add production-page Storybook examples and browser tests for both
interfaces.

## Verification

- Linux checkout, Node 25.9.0, system Chromium 148.0.7778.96.
- The final change includes master through `07d9316218`. It uses the
shared routine creation form and the upstream Runner test and SDK
source-pin fixes.
- 68 tests pass across eight focused UI suites at `440a9eb6a7`. UI
typecheck, token gates, and whitespace checks pass.
- Two new directory-error cases fail before the fix and pass after it.
Both pages keep routine rows mounted, show an error with Retry, and
restore responsible names after retry.
- 59 checks pass across the SDK source-pin, public-type, and evidence
suites.
- The Runner test program typechecks after building its eval dependency.
A local run of the native-session test file passed 300 tests. One
additional test could not run because the local debug Runner binary was
absent. CI must cover that case.
- Storybook builds and all 13 browser checks pass on
`64a87af7c085426d09eb8aa48bf9491487565990` after the latest master
integration. They cover current and Classic controls, filters, columns,
links, selection alignment, Recent Runs, mobile overflow, and shared
toolbar behavior.
- Storybook examples: Default, LinkedFilters, Classic, ClassicSelection,
and ClassicRuns. They mount production pages with fictional API
responses. Screenshots cover light, dark, filters, custom columns, and
mobile. The baseline manifest has no snapshots; these are visual review
captures.
- Earlier preference, shared-link, title-link, compact-row, and
filter-render-cost regressions have red/green evidence. The
scheduled-routine journey has 17 passing unit checks from the prior
revision.
- The shared selector has three large-list cases with 1,200 routines and
120 folders. All filters are active. Each case checks row order and
folder counts. Work counters throw if filtering repeatedly scans
selected IDs or folder counts scan the routine list for each folder.
Both deliberate regressions fail; the unchanged selector passes. Both
Routines pages use this selector. The latest commit adds only these
tests; production source is unchanged.
- [CI at
`64a87af7c0`](https://github.com/paperclipai/paperclip/actions/runs/44416091562)
passed all jobs, including typecheck, Build, Runner, general tests,
serialized tests, and E2E. [Final-head CI at
`440a9eb6a7`](https://github.com/paperclipai/paperclip/actions/runs/44419144971)
now passes on attempt 2. All 52 executed jobs pass; one file-selection
job is skipped. Typecheck, Build, all test shards, E2E, Runner, and the
aggregate verify gate pass. The first attempt failed in the
timing-sensitive watchdog fixture; its retry passes.
- `pnpm verify` returned exit 2 because this branch needs broad CI
coverage. Final-head CI passes. Greptile and Ponytail both give 5/5 at
`440a9eb6a75184a35001e99a17e6856b7cdb0bd5`. All 20 inline threads are
resolved.
- Prior CI at `10a5b0813b` passed all general and serialized test
shards, all E2E shards, and Build. It failed on a circular test-mock
type and a stale SDK source pin. Master now contains both repairs; the
final branch uses those repairs.
- The two Routines page bodies were already duplicated. This PR reduces
them and shares list data, controls, rows, and view state. Codie owns
the remaining page-shell consolidation as later work.
- Live provider execution and scheduler behavior are outside this
presentation change. Protected Storybook publication still requires a
configured human reviewer; no deployment approval is inferred from merge
authorization.

## Risks

View settings now include filters. A person can return to a filtered
list. The URL and active filter button show that state. Shared filter
URLs override local filters. Column choices stay local. The shared
filter extraction can affect Tasks, so its component and toolbar checks
are included. No migration is needed.

## Model Used

OpenAI GPT-6 through Codex. The runtime does not expose a more specific
model revision. Used reasoning, source editing, shell tools, and browser
automation. No sub-agents 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>
2026-11-18 17:43:29 -06:00
DottaandClaude Opus 5.5 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>
2026-11-18 17:34:09 -06:00
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>
2026-11-18 14:27:00 -08:00
DottaandClaude Opus 5.5 4b189690b4 docs(plans): stage production settings for the team's next deploy (#22224)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud now sends analytics directly to PostHog, and this is
live on staging
> - The plan doc records the rollout state and the steps that remain
> - Production needs an ordered, reversible rollout with clear decisions
> - This pull request records how production settings are staged for the
team's next deploy
> - The benefit is one reviewed place that says what is done, what is
next, and how to roll back

## Linked Issues or Issue Description

**What is the problem?**
Production app deploys are coordinated by the team, and the plan needs a
way to prepare the settings without restarting user stacks.

**What do you propose?**
Record the revised production approach: stage settings now without
restarting user stacks, and let the team's next production deploy turn
them on. Add a note for that deploy with what turns on, canary checks
and rollbacks.

**Why does it matter?**
Production changes must be ordered and reversible, and the open
decisions must be visible.

## What Changed

- Add "Revised plan" and "Note for the team's production deploy" to
Phase 5 of `doc/plans/2026-11-17-cloud-direct-posthog.md`.
- No code changes.

## Verification

- Documentation only.

## Risks

- Low risk. Documentation only.

## 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>
2026-11-18 15:43:46 -06:00
DottaandClaude Opus 5.5 35563b7de5 fix(railway): report restricted environments instead of a consent error (#22214)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - The Railway connection gives agents governed deployment tools, such as `list-deployments`
> - Railway Environment RBAC lets non-admin members see a restricted environment, but Railway denies reads of its services, deployments, and logs
> - The client maps this denial to `railway_api_authorization_required` and tells the user to reconnect or to use IDs from a consented workspace
> - That advice is wrong for this case: workspace consent is correct, and reconnecting does not change the result
> - This pull request identifies the restricted environment and reports the correct remedy
> - The benefit is that agents and operators get a clear, actionable error instead of an incorrect reconnect loop

## Linked Issues or Issue Description

(B) No public issue exists. Bug description:

**What happened?**
An agent called `paperclip-railway-list-deployments` for a service. In the same session, `list-projects`, `list-services`, and `list-environments` succeeded for the same project. The deployment-history call failed every time with `railway_api_authorization_required` and the message "Use IDs from a workspace selected during consent, or reconnect". The project-level reads prove that workspace consent is correct. The denied environment is restricted for the connected member, so the message sends the user to the wrong fix.

**Expected behavior**
When Railway denies the environment-scoped target check because the environment is restricted, the tool must report a distinct error. The error must say that a Railway project admin must grant access. It must not tell the user to reconnect.

**Steps to reproduce**
1. Connect Railway with a member (non-admin) account in a workspace that has a restricted environment.
2. Call `paperclip-railway-list-environments` for the project. The restricted environment is in the list.
3. Call `paperclip-railway-list-deployments` (or `service-status`) for a service in that environment.
4. Railway returns `Not Authorized`, and Paperclip reports a workspace consent error.

**Paperclip version or commit**
`master` at 8282d386da.

## What Changed

- `server/src/services/railway.ts`: When the target query fails with an authorization denial, the client reads the project's environments with `canAccess`. If the requested environment has `canAccess: false`, the client throws `railway_environment_restricted` (HTTP 403) with the admin-access remedy. In all other cases, the client throws the original error. If the access check fails, the client also throws the original error. The access check is a read query. No mutation runs after a denied target check.
- `server/src/services/railway.ts`: `list-environments` now returns `canAccess` for each environment, so agents can choose an accessible environment before they call a target tool.
- `server/src/__tests__/railway.test.ts`: Adds a regression test for the restricted, accessible, and unknown cases.
- `doc/connections/RAILWAY.md`: Adds a recovery entry for the new error code.

## Verification

- Failing before the fix: `cd server && npx vitest run src/__tests__/railway.test.ts`. The new test "reports a restricted environment instead of a workspace consent error when Railway denies the target" failed. It expected `code: "railway_environment_restricted"`, but it received `code: "railway_api_authorization_required"`. The other 28 tests passed.
- Passing after the fix: the same file passes (29/29).
- Related suites pass: `npx vitest run src/__tests__/railway.test.ts src/__tests__/railway-connection.test.ts src/__tests__/railway-ssh.test.ts src/__tests__/connector-tool-policy.test.ts` (4 files, 63 tests).
- Scoped `tsc --noEmit` with the server `tsconfig.json` for the changed files passes.
- Not run: the full server typecheck and `pnpm verify`. In the test sandbox, they used more than the 8 GB memory limit. CI must confirm them.
- Public reference for the provider behavior: https://docs.railway.com/enterprise/environment-rbac

## Risks

- Low risk. The change applies only after Railway has already denied the target check. It adds one read query in that case.
- If Railway removes or renames `canAccess`, the access check fails, and the client throws the original error, as before this change.
- The access check reads the first 100 environments of the project. If a project has more environments, the client throws the original error.
- `list-environments` output gets one more field.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), agentic coding 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
- [ ] 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>
2026-11-18 15:26:56 -06:00
DottaandClaude Opus 5.5 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>
2026-11-18 15:24:11 -06:00
84a529df4f fix(monitors): let low-trust reviewers schedule a self-wake on their own task (#22212)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use the `set_task_monitor` tool to save a timed follow-up
check on their task
> - Agents that run with the `low_trust_review` preset (for example,
pull request reviewers) cannot save this check
> - The tool requires company-wide `runtime:manage` access, and the
preset denies that access
> - Thus a reviewer must wait for a different event before it can
continue its review
> - This pull request lets the assignee save or clear a self-wake
monitor on its own task, and keeps the company-wide restriction
> - The benefit is that reviewers can continue their own review on time,
with no new company-wide access

## Linked Issues or Issue Description

**What happened?**

A `low_trust_review` agent calls `set_task_monitor` on its own
in-progress task. The call fails with this error: "low_trust_review
agents cannot use company-wide or privileged runtime:manage APIs by
default." The tool is advertised to the agent, but the agent cannot use
it. The agent cannot schedule its own follow-up check.

**Expected behavior**

The assignee can schedule or clear a monitor that only wakes itself on
its own task inside its trust boundary. Monitors that create recovery
tasks or escalate to the board stay denied. Company-wide
`runtime:manage` stays denied.

**Steps to reproduce**

1. Assign an in-progress task to an agent.
2. Start a native run for that task with a `low_trust_review` execution
policy whose boundary root is the task.
3. Call `set_task_monitor` with a future `nextCheckAt` and notes.
4. See the 403 error with reason `deny_low_trust_boundary`.

**Paperclip version or commit**

`master` at 8282d386da.

## What Changed

- `assertCanManageIssueMonitor` accepts an optional own-task scope. With
this scope, a `deny_low_trust_boundary` result for `runtime:manage` does
not block the assignee when both the requested monitor and the stored
monitor are the assignee's own self-wake (`wake_owner` recovery,
scheduled by the assignee, not the provider-quota service) or are empty.
- The native `set_task_monitor` tool passes this scope only when the
agent, project and task policies alone resolve the same low-trust
boundary as the current run. A monitor wake starts a run from those
sources, not from the run snapshot. Thus the woken run keeps the same
low-trust limits. A low-trust boundary that only the run snapshot
carries is still denied.
- The tool still checks `issue:read` and `issue:mutate` on the target
first, and still requires an in-progress or in-review task assigned to
the calling agent.
- The `create_recovery_issue` and `escalate_to_board` recovery policies
still require `runtime:manage`. The assignee also cannot clear or
replace a board-scheduled, recovery, escalation or provider-quota
monitor.
- The HTTP issue routes do not change.
- `doc/LOW-TRUST-PRESETS.md` describes the new rule.

## Verification

- Test 1 failing before the fix: `pnpm vitest run
src/services/native-runtime/task-monitor.integration.test.ts -t
"low-trust reviewer"` (in `server/`). The new test failed: `promise
rejected "Error: low_trust_review agents cannot use company-wide or
privileged runtime:manage APIs by default."` from
`assertCanManageIssueMonitor`, with `{ status: 403, details: { reason:
'deny_low_trust_boundary' } }`.
- Test 2 failing before the trust fix: `pnpm vitest run
src/__tests__/issue-monitor-scheduler.test.ts -t "low-trust limits"`. A
run with a low-trust policy only in its snapshot could save a monitor
(`promise resolved ... instead of rejecting`). After the fix, that call
is denied. When the task carries the policy, the monitor is saved, the
real scheduler fires it, and the woken run resolves to
`low_trust_review` with the same boundary.
- Test 3 failing before the stored-monitor fix: the extended "low-trust
reviewer" test cleared a board `escalate_to_board` monitor (`promise
resolved ... instead of rejecting`). After the fix, clear and replace
are denied for board-scheduled, `escalate_to_board`,
`create_recovery_issue` and provider-quota monitors.
- Passing after: `task-monitor.integration.test.ts`,
`issue-monitor-scheduler.test.ts` and
`native-preserved-monitor-wait.test.ts` pass (100/100).
- `pnpm run typecheck` in `server/` passes.
- I did not run the full `pnpm verify`.

## Risks

- Low risk. The change applies only to the native tool, only to the
assignee, and only to the task-scoped `wake_owner` monitor. A monitor
wake goes only to the same agent on the same task, and that run resolves
the same low-trust boundary.
- The bypass depends on the `deny_low_trust_boundary` decision reason.
Other denials (for example, a viewer responsible user, a task bridge
key, or a skill-test token) still block the call.

## 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
- [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: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:19:11 -06:00
DottaandPaperclip 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>
2026-11-18 15:08:04 -06:00
911fe5bb9a Fix Recents ordering and add sidebar pins (#22219)
## 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.
> - Recents should reflect the order in which a person opened their
tasks.
> - Opening a task only updated its saved details. It did not update the
visit time.
> - This pull request records task visits and adds Recents shortcuts to
the existing sidebar pins.
> - People can find their last task and keep frequently used items above
More.

## Linked Issues or Issue Description

**What happened?**

Opening a personal task left it in its old position or added it at the
bottom of Recents. The Recents rows also had no controls to pin their
items.

**Expected behavior**

Opening a task moves it to the top of Recents. Opening a nested task
moves its parent group to the top. A person can pin a task, chat, or
project from Recents.

**Steps to reproduce**

1. Open two personal tasks in the Coordinator workspace.
2. Reopen the first task and check its position in Recents.
3. Hover over a Recents row and look for a pin button.

**Paperclip version or commit**

Reproduced on source checkout `43b2d8be22`.

**Deployment mode**

Local dev with an isolated embedded PostgreSQL database.

Related work: #22024, #21649, and #19685.

## What Changed

- Record the first loaded task visit and subsequent reopens. Keep the
timestamp during background refreshes.
- Use the most recent task visit in each displayed group when ordering
parent rows.
- Add tasks, agent chats, and projects from Coordinator Recents to the
existing sortable sidebar pins. Resolve saved shortcuts with the current
company data and task read permissions.
- Use the same highlight state for a Recents row and its pin button.
This includes the current row, hover, and keyboard focus.

## Verification

- The reopen test failed before the fix because the older task stayed
below the newer task. The Chromium check also reproduced the missing pin
on the current row before the highlight fix.
- Ran the eight focused Vitest files for task detail, the two sidebars,
recent task state, task warmup, and pinned navigation on macOS. Ran
`pnpm --filter @paperclipai/ui typecheck`.
- In Chromium on the isolated dev server, opened two tasks and reopened
the first. Pinned a task and project and confirmed that both survived
reload. Checked current, hovered, and keyboard-focused rows. Checked
that a pointer click did not keep the pin visible after leaving an
inactive row.
- `pnpm verify` requested broader CI coverage because the product
documentation changed.

- GitHub CI passed on `b77fc06393`. The initial native-server and Canary
jobs lost their runners. Both jobs passed on retry without a code
change. [CI
retry](https://github.com/paperclipai/paperclip/actions/runs/44373716458/attempts/2)
- Greptile scored the same commit 5/5 and left no review threads.
[Greptile
review](https://github.com/paperclipai/paperclip/pull/22219#issuecomment-6988318333)

## Risks

- Recent ordering keeps the existing participation filter and subtask
groups. A task pin uses the existing summary batch to check read access
independently of participation.
- Pins are stored per browser user. Task and project keys include the
company ID. Existing page and agent-chat keys keep their saved order.
- The change uses the existing summaries API. It requires no schema
migration.

## Model Used

- OpenAI GPT-6 via Codex, with shell, GitHub CLI, and Chromium
verification 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 linked existing issues or described the issue using
the relevant issue template
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket ID
- [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>
2026-11-18 12:52:37 -08:00
DottaandClaude Fable 5.2 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>
2026-11-18 13:13:15 -06:00
Devin FoleyandPaperclip f4d44ac13e fix(ui): keep GitHub identity widgets out of replies (#22217)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents call connected apps while they work on tasks.
> - Some app tools include a widget that Paperclip shows with the reply.
> - GitHub identity lookups include a profile widget. Repeated lookups
fill the reply with copies of the same card.
> - This pull request omits the known GitHub identity view when
Paperclip selects reply widgets.
> - The benefit is that task replies show useful app results while
identity calls remain in the tool history.

## Linked Issues or Issue Description

**What happened?**
A task that reads GitHub activity showed four copies of the connected
account's profile widget. Each copy came from a successful `get_me`
call. Paperclip showed these intermediate lookup results with the reply.

**Expected behavior**
GitHub identity lookups stay in the folded tool history. Other app
widgets keep their normal reply placement.

**Steps to reproduce**
1. Connect GitHub through its MCP server.
2. Run a task that calls `get_me` several times to find the connected
account.
3. Open the task reply. Each lookup adds a profile card.

**Paperclip version or commit**
Reproduced in the UI tests against base commit `8285a81280db`.

**Deployment mode**
Authenticated server. The rendering path is shared with local instances.

Related work: [MCP Apps
support](https://github.com/paperclipai/paperclip/pull/21119), [MCP Apps
reply views](https://github.com/paperclipai/paperclip/pull/21266).
Searched open issues and PRs for `get_me`, GitHub widgets, and MCP Apps.
No duplicate fix was found.

## What Changed

- Omit a view from the reply index only when its upstream tool is
`get_me` and its resource is `ui://github-mcp-server/get-me`.
- Apply the filter before the per-run widget limit. This covers saved
history and live replies through their shared index.
- Add tests for repeated saved identity calls, widget pagination, and
other GitHub and app views.
- Document the display policy in the MCP Apps guide.

The MCP Apps UI owns reply selection. Tool execution, view storage, API
responses, and the folded tool history keep their existing behavior.

## Verification

- Red-green reproduction: the three new regression tests failed before
the source change and passed after it.
- `pnpm exec vitest run ui/src/components/mcp-app/`: 6 files, 36 tests
passed.
- `pnpm --filter @paperclipai/ui typecheck`: passed after building the
worktree's missing SDK declarations with `pnpm --filter
@paperclipai/plugin-sdk ensure-build-deps`. The first typecheck failed
because those generated declarations were absent.
- `git diff --check`: passed. Reviewed the diff for secrets, personal
data, and run artifacts.
- `pnpm verify --explain`: exited 2 because the guide is a global CI
input. Required CI must supply broad coverage. An earlier selection was
invalidated by the guide edit and was rerun.
- Browser acceptance and a deployed staging check have not been run. The
saved-widget regression uses the shared React reply component.
- [Greptile
review](https://github.com/paperclipai/paperclip/pull/22217#issuecomment-6988213101):
5/5 for head `c842d21bff6de1b2084593abfff69e789775b163`, with no
actionable findings or unresolved review threads. Required CI is still
running.

## Risks

- Low risk. The display filter matches one known tool and resource pair.
Other widgets remain visible.
- This release hides GitHub profile cards even when a task intentionally
calls this tool to read a profile. The text result remains in the tool
history.
- No schema migration or stored-data cleanup is required. Existing saved
cards disappear from replies after the updated UI loads.

## Model Used

- OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through Codex in T3 Code, with
xhigh reasoning effort, 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
- [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>
2026-11-18 11:11:51 -08:00
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>
2026-11-18 12:48:49 -06:00
Devin FoleyandPaperclip 8285a81280 fix(native): retry a fresh launch whose provider pack could not be verified (#22106)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Before a remote native run starts its provider, the controller
selects a provider pack and verifies it in the sandbox
> - The verification command retries once. If both reads fail without a
result (a timeout, a signal, or a transport error such as HTTP 502), the
run fails with `runner_remote_provider_verification_unavailable`
> - That code holds the run for a person in every case. The hold exists
for reattachment, which does not spend a new provider attempt and could
loop
> - On a fresh launch the code is also not on the list of failures that
prove no provider session started. So the run is classified as
"ambiguous state", and the task waits behind a Board-owned Retry
> - This pull request retries a fresh launch's unverified pack on the
same run, within the provider attempt budget, and keeps the hold for
every other attempt
> - The benefit is that a short sandbox outage during startup no longer
stops a chat or task until a person clicks Retry

## Linked Issues or Issue Description

**What happened?**
A chat message started a fresh native run on a new sandbox. The
preinstalled provider pack did not match, so the controller uploaded the
pack. Both reads that verified the uploaded pack failed with "Request
failed with status code 502". No provider process started. The run
failed with `runner_remote_provider_verification_unavailable`, the
recovery mode was `ambiguous_state`, and the chat showed a Retry button.
A manual Retry then succeeded.

**Steps to reproduce**
1. Start a fresh remote native run.
2. Make both provider-pack verification reads fail without a result, for
example with a 502 from the sandbox command API.

**Expected behavior**
The run retries its startup on the same run, with backoff, because no
provider session started.

**Actual behavior**
The run is held for a person with "Inspect the original provider failure
and explicitly resolve the ambiguous session state".

## What Changed

- `native-session-executor.ts`:
- `nativeProviderRecoveryEvidence` treats
`runner_remote_provider_verification_unavailable` as definitely
pre-session when the attempt is a fresh bootstrap (the caller passes
`bootstrap`). As for every pre-session code, this applies only when the
run has no checkpoint and no provider event.
- `nativeSessionFailureDisposition` takes an optional `freshBootstrap`
flag. With it, `runner_remote_provider_verification_unavailable` is
retryable instead of permanent, so the existing same-run startup retry
and its three-attempt budget apply. The executor passes the same
fresh-bootstrap condition it already uses for `bootstrap`.
- Reattachment, warm session recovery and retained transitions do not
pass `bootstrap`, so they keep the hold.
- `doc/native-workspace-finalization-recovery.md`: describe the
fresh-launch retry.
- Tests: the disposition retries attempts 1 and 2 of a fresh launch and
stops at attempt 3, and the existing reattachment hold test is
unchanged. An integration test shows `bootstrap_retry` for a fresh
launch with no checkpoint, and `ambiguous_state` without `bootstrap`.

## Verification

- `npx vitest run` on the new cases: pass. Both fail without the source
change.
- `npx vitest run` on the native session executor, controller recovery,
remote provider pack, online source, status arbiter corpus, continuation
and startup/retry suites: 2203 pass, 8 skipped.
- `npx tsc --noEmit` passes for the server.

## Risks

- Low. Only a fresh launch with no checkpoint and no provider event
changes. A deterministic verification outage now costs up to two more
startup attempts, with backoff, before the run is held.
- A completed verification that fails
(`runner_remote_provider_artifact_incompatible`) is unchanged.

## 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>
2026-11-18 10:40:31 -08:00
DottaandClaude Opus 5.5 adb2bcf896 fix(connectors): activate plugin connectors with agent grants and no sign-in (#22201)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Plugins can now add connector types (#22004) and serve their tools
with the `plugin` transport (#22019)
> - A plugin connector method can declare `grantKinds: ["agent"]` with
`auth: "none"` or `"api_key"`
> - Such a connector cannot reach its agent: the connect form cannot
name the agent, connect creates no agent grant, and Paperclip Runner
runs never list plugin-transport tools
> - The product rule is that a plugin connector behaves exactly like any
existing connector
> - This pull request fixes the connect form, creates the agent grant at
connect, and lets runner runs list plugin-transport tools
> - The benefit is that an operator can activate a per-agent plugin
connector, and only the chosen agent gets its tools

## Linked Issues or Issue Description

Refs #22004
Refs #22019

**Subsystem affected**
Connectors (connect wizard, tool access service), Paperclip Runner
assigned-tool gateway.

**Problem or motivation**
A plugin connector with agent grants and no sign-in cannot be activated:
1. Connect form: it says "No sign-in needed, available to all agents".
"Change" shows "No identity required" and "Which agent owns this GitHub
account?", with no agent picker. Connect sends `grantKind: "agent"`
without `subjectAgentId`, and the server rejects it with a validation
error. The "Finish setup" resume form has the same problem.
2. Grant: connect with `subjectAgentId` saves a `per_agent` connection
with zero grants. Finish adds the agent install, but there is still no
grant. Only the OAuth callback writes agent grants, and these methods
have no OAuth step. For `api_key` methods connect fails, because the
health check finds no agent grant, and the key has nowhere to go.
3. Runner: a Paperclip Runner run builds its assigned-tool gateway from
an allowlist of transports (`mcp_remote`, `local_stdio`, REST, Browser
Use, GitHub bot, voice). `plugin` is not in it, so the run sees no
plugin-transport tools, even when the install, profile and grant allow
them.

**Proposed solution**
Create the agent grant at connect for curated methods without sign-in.
Add `plugin` to the runner assignment and its digest. Show a one-agent
picker with connector-neutral copy.

**Expected behavior**
Connecting alone grants no tools. Finish with agent A gives only agent A
the tools, in gateway discovery and in a runner run. The connection has
exactly one active agent grant, for A.

## What Changed

- `server/src/services/tool-access.ts`: `connectGalleryApp` writes an
active agent grant for `subjectAgentId` when a curated method with
`auth` `none` or `api_key` uses `grantKind: "agent"`. The API key goes
on that grant, not on the connection. A resume without `subjectAgentId`
keeps the agent of the existing grant and keeps its saved key. A second
agent on the same connection is a 409 conflict. The grant write is
audited and joins the existing revive rollback.
- Finish does not create agent grants. Finish carries no credential, and
it can list many agents while a per-agent connection has one identity. A
credential-less grant would also claim a connected OAuth identity that
does not exist. The grant comes from connect (or the OAuth callback).
Finish creates only the install.
- `server/src/services/heartbeat/run-preparation.ts` and
`native-runtime/runtime-context.ts`: include the `plugin` transport in
the runner assignment and in its digest (the two lists must match).
- `ui/src/features/connections/ConnectionSetupFlow.tsx`: for an agent
grant, show the agent picker (exactly one agent), keep the install
choice on "specific", open the "Change" panel and disable Connect until
one agent is chosen, and send `subjectAgentId`. Copy is neutral ("Which
agent uses this connection?"); the GitHub copy stays for GitHub. The
summary no longer says "available to all agents" for an agent grant.
Finish sends the chosen agent, never `all_agents`, for an agent grant.
- `doc/connections/CONNECTOR-PLAYBOOK.md`: document agent grants for
methods without sign-in.

## Verification

Each new test failed before its fix and passes after it:
- `server/src/__tests__/plugin-connector-agent-grant.test.ts` (embedded
Postgres, real routes and gateway):
- `auth: "none"` + agent grants: after connect, no agent has tools;
after finish with agent A, A's discovery lists the tools and B's lists
none; exactly one active agent grant, for A. (Red: zero grants.)
- `auth: "api_key"` + agent grants: same, the key is on A's grant, and a
tool call receives it. (Red: connect returned 422.)
  - A second agent on the same connection is a 409. (Red: 201.)
- Resume of an API-key draft without the key keeps the key on the grant.
- Paperclip Runner session: `buildPaperclipRuntimeMcpServers` +
`createAssignedMcpTools` list the installed plugin tools for A, and
search by the manifest tool name (`update_record`) finds the gateway
tool. B gets none. (Red: no tools.)
- Regression: an organization-grant method keeps one default
organization grant, and both agents get the tools with `all_agents`.
- `ui/src/pages/apps/AppsConnect.test.tsx`: for `none` and `api_key`
agent-grant plugin methods, the form shows the picker, has no GitHub or
"available to all agents" copy, blocks Connect until an agent is chosen,
and sends `subjectAgentId`. (Red: "available to all agents" shown.)
- Regression suites: `plugin-connectors-plugin-transport`,
`plugin-connectors-circleback-parity`, `heartbeat-runtime-mcp-servers`,
`run-preparation`, `tool-access-service`,
`tool-access-oauth-protocol.integration`, `generic-mcp-connection`
(OAuth, GitHub per-agent and organization flows) pass. UI:
`src/features/connections`, `src/pages/apps`, `App.deep-link-routing`
pass (66 files, 1103 tests).
- `tsc --noEmit` passes for `server` and `ui` source. `pnpm
check:module-boundaries` passes.

## Risks

- Low. The grant change applies only to curated methods with agent
grants and no OAuth. Organization, personal and OAuth flows keep their
code paths.
- The runner change makes plugin-transport tools visible to runner runs.
Access still needs an install, a profile and a grant, and every call is
re-authorized by the gateway.
- Connections created before this fix have no agent grant. Connecting
again (or "Finish setup") with the agent creates 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>
2026-11-18 11:25:25 -06:00
DottaandClaude Opus 5.5 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>
2026-11-18 10:52:20 -06:00
DottaandPaperclip 875e4d375e fix(auth): preserve identity across connection request handoffs
Continue accepted connection requests as the verified recipient and retain their original audit parent. Keep declined and automatically closed requests on the source identity. Preserve the latest accepted retry context, ordinary preparation retries, and saved approval origins.

Verification: 209 focused local tests passed. Final-head CI passed, Greptile and both Paperclip reviewers rated the change 5/5, and all review threads are resolved.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-18 10:45:55 -06:00
e2dda16b52 docs(plans): record the AWS connector spike findings (#22191)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The planned AWS connector gives each connection its own AWS identity
with no stored keys, using the workload identity issuer from #22083
> - The plan had open questions that only a real AWS account could
answer
> - This pull request records the answers from a spike against the
Paperclip dev AWS account
> - The benefit is that the connector build starts from proven facts,
and two design details are corrected

## Linked Issues or Issue Description

Refs #22083.

**Subsystem affected**
Connections (planned AWS connector), docs only.

**Problem or motivation**
The AWS plan assumed an `aws___call_aws` tool and a read-only session
policy with only `ReadOnlyAccess`. Neither had been tested.

**Proposed solution**
Record the spike results and correct the plan. The hosted server in the
test account offers `aws___run_script` but no `aws___call_aws`. A
read-only session also needs `AWSMCPSignInOAuthAccessPolicy`, or the
token exchange fails.

**Alternatives considered**
Leave the plan unchanged and find the differences during the build.
Rejected: the tool choice changes the governance design.

## What Changed

- `doc/plans/2026-11-17-aws-connector-and-minted-credentials.md`: a new
"Spike findings" section with results and timings, and corrections in
the minting, agent-call and governance sections. Phase 0 is marked done.

## Verification

- Spike against the dev AWS account. The issuer code from #22083 ran
locally behind a temporary public HTTPS tunnel. The spike verified these
items:
  - AWS accepted a Paperclip-signed token.
  - A token for another connection was denied.
  - The bearer exchange worked.
  - `tools/list` worked.
  - A read and a write through `run_script` worked.
  - A read-only session could read, and AWS refused its write.
  - Both access-key paths worked.
- After the spike, a listing of roles, OIDC providers, users and buckets
with the spike prefix returned nothing.
- Docs only. No code changed.

## Risks

- Low risk. Docs only.
- The tool list was observed in one account on one day. AWS can change
the hosted server.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, AWS SDK for JavaScript, AWS CLI, a Cloudflare quick tunnel).

## 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>
2026-11-18 10:34:28 -06:00