Commit Graph
8302 Commits
Author SHA1 Message Date
7a0ac92fdf fix(runner): tell ACPX agents which field a refused semantic call failed (#22037)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents call Paperclip semantic tools (for example
`request_human_input`) through the runner, and the ACPX runner sends
each refusal back to the agent
> - Today the ACPX runner replaces every refusal with the fixed text
"Paperclip semantic operation failed"
> - The real reason (for example `summary: too big, max 1000`) is only
in the run events, so the agent cannot see it
> - Agents then retry the same bad input. One agent retried a questions
card 5 times with the same too-long prompt
> - This pull request adds the stable error code and, for a validation
refusal, each failing field path with its rule and limit to the message
> - The value the agent sent, free-text messages and server errors (5xx)
stay hidden, as before
> - The benefit is that agents can fix a refused call on the next try
instead of retrying blind

## Linked Issues or Issue Description

Refs #20134 (fixes one case of this problem: the advertised
`request_human_input` bounds)

**What happened?**
An agent called a semantic tool with input that failed server
validation. The tool result said only "Paperclip semantic operation
failed". The agent retried the same input 5 times, and each retry failed
the same way. The run events showed the real cause: `summary: too big,
max 1000`.

**What did you expect to happen?**
The tool result should say which field failed and which rule it broke,
so the agent can correct the input. It should not echo the input value
or internal diagnostics.

**Steps to reproduce**
1. Run an agent on an ACPX provider.
2. Call `request_human_input` with a `prompt` of 1,100 characters
(before #20134), or any semantic tool with input that fails zod
validation.
3. See the generic "Paperclip semantic operation failed" in the tool
result.

## What Changed

- New `acpx_tool_failure_feedback` module in `runner-core`. It reads a
failed tool result and builds a bounded message from:
- a stable error code (lowercase words joined by `_`, `.` or `-`, for
example `paperclip_runner_agent_not_found`);
- zod-style issues: field path, rule name, type and numeric limit, for
example `payload.prompt: too_big, string max 1000`.
- It reads the result as an object, an issue list, or a `{success:false,
contentItems:[{inputText}]}` envelope whose text is JSON or starts with
`code:`.
- It never copies `message`, `input`, free text or the input value. Path
keys and rule names that do not look like names become `*` or `invalid`.
It shows at most 5 issues and 8 path segments.
- Any result with a status of 500 or more, or with no recognizable code
or issue, keeps the generic message.
- `AcpxProviderSession` uses this message for non-terminal semantic
failures. Reserved terminal tools keep their current feedback.
- Fake ACPX sidecar mode `resolutions-error-detail` and an integration
test that checks the message crosses the sidecar boundary without the
value.

## Verification

- `cargo test -p runner-core --lib acpx_tool_failure_feedback` (7 unit
tests: issue lists, envelopes, codes, server errors, free text, masking,
bounds).
- `cargo test -p runner-core --test acpx_provider_resolutions` (new
`tells_the_agent_which_field_failed_validation_without_its_value`, and
the existing redaction test still gets the generic message).
- `cargo fmt --check`.

## Risks

- Low to medium. The main risk is data in error text. The module copies
only values that match strict name and number patterns, and never a
`message` or `input` field. Tests check that sample values do not appear
in the output.
- Agents see a longer error message for validation refusals. The message
still starts with "Paperclip semantic operation failed", so text matches
on that prefix keep working.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in an agent harness.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1119.0-canary.830200
2026-11-18 16:49:11 -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
e2cee049f9 fix: show instruction saves in history, credit the real writer, and speed up the agent tool-rule list (#19515)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Operators and agents change agent instructions (AGENTS.md), and they
must see who changed them and when
> - Agent files replaced instruction revisions. Saves no longer write
revision rows, so instruction history is empty
> - The current revision is stamped with the reader and the date
1970-01-01, so it gives false audit data
> - Separately, an agent that lists tool rules gets a timeout when many
rules name the same resources
> - This pull request reads history from the save records that Paperclip
already writes, credits the real writer, and checks each tool-rule
resource one time
> - The benefit is a correct audit trail for instruction changes and a
tool-rule list that agents can read

## Linked Issues or Issue Description

No public issue exists. I searched open and closed issues and PRs for
these problems and found none.

**What happened?**
1. `get_agent_instruction_history` (and the history API) returns 0
revisions for an agent whose AGENTS.md was saved many times. The
activity log shows each save as `agent.files_updated` with the path,
content hash, actor and run.
2. `read_agent_instructions` returns a current revision with `createdAt`
1970-01-01. Its actor is the agent that reads it, and its `sourceRunId`
is the run that reads it.
3. `GET /api/companies/{companyId}/tools/policies` from an agent fails
with a transport timeout most of the time when the company has many tool
rules. A board user gets the list without a problem.

**Expected behavior**
1. History lists each save, newest first, with its writer, run, source
and time.
2. The current revision names the agent or user that wrote those bytes,
and the time of that save. If no save is recorded, it names no writer.
3. The agent gets the tool-rule list in normal time, with the same rules
hidden as before.

**Steps to reproduce**
1. Save an agent's instruction entry file (board editor,
`update_agent_instructions`, or a run that edits the file). Read the
history. It is empty.
2. As a different agent, call `read_agent_instructions` on that agent.
The revision shows the reader and 1970-01-01.
3. Create about 40 tool rules that name the same connection and agent.
As an agent, list `/tools/policies`. Each rule does a new set of access
checks for each resource, one after another.

**Paperclip version or commit**
`master` at `819420a60a`.

**Deployment mode**
Hosted. The new tests reproduce all 3 problems on `master`.

## What Changed

- `agent-instruction-revisions.ts`: history merges the legacy revision
rows with the `agent.files_updated` save records for the entry file. The
order is `(created_at, id)` descending, and cursors keep PostgreSQL
timestamp precision.
- `agent-instruction-revisions.ts`: the current revision takes its
writer, run, source and time from the latest save of the same content
hash. A reader is never the writer. Bytes with no save record have no
writer.
- `agent-instruction-revisions.ts`: an identical re-save over bytes with
no record is marked `source: "adopted"`. It repairs the runtime journal
but is not listed as a save.
- `agent-instruction-revisions.ts`: a history ID can be a legacy
revision, a save record, or the current content token. A save record
keeps only metadata. If its bytes are no longer current, a read returns
404 with `INSTRUCTION_REVISION_CONTENT_NOT_RETAINED`.
- `agent-file-store.ts`: saves record `byteLength`. A run collection
that changes the entry file records its path, hash and size, so history
shows saves from runs.
- `connection-management-authz.ts`: `filterConnectionManagementPolicies`
keeps one read decision for each distinct resource in a request, and
loads each application or catalog entry one time. A rule is still hidden
when any resource that it names is hidden. Board callers do not use this
path.
- Tests: new tests for save history, paging, writer credit, adoption,
and the tool-rule list. Old assertions that expected empty history now
check the exact saves.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/agent-instruction-revisions.test.ts
src/__tests__/agent-instruction-working-copies.test.ts
src/__tests__/agent-directory-working-copies.test.ts
src/__tests__/built-in-agents.test.ts
src/services/native-runtime/agent-instruction-tools.integration.test.ts
src/__tests__/tool-policy-list-authz.integration.test.ts`
- With the fix: all pass (revisions: 28 passed, 1 skipped on Linux;
other 5 files: 230 passed).
  - With the new tests on `master` code: 13 tests fail, as expected.
- `src/__tests__/connection-management.integration.test.ts`: 90 passed.
- The new tool-rule test lists 40 rules that name 1 connection and
counts the connection reads. It needs fewer than 10.
- I could not run the full server typecheck in my sandbox because of a
memory limit. CI runs it.
- CI on head `a2f0b825`: all checks pass, including `ci / verify` and
`ci / e2e`.

## Risks

- History now shows entries whose ID is an activity row ID, not a
revision row ID. Clients that read or restore an older save get a clear
404 because Paperclip no longer keeps those bytes. The latest save and
legacy revisions still read and restore as before.
- Saves recorded before this change have no `byteLength`. For those,
history shows the current size when the hash matches, and 0 otherwise.
- Stock updates of built-in agents do not record a file path, so they do
not show in history.
- No migration. No change to the stored data model.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with
tool use (shell, file edits, test runs). Standard context window.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [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>
Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com>
2026-11-18 16:41:53 -08: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
6b980871b5 fix(grok-local): copy SSH skill contents into the created directory (#22120)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The `grok_local` adapter can run a Grok agent on a remote SSH
workspace
> - Before the run, `prepareGrokRemoteProjectAssets` copies the selected
skills into `.claude/skills` on the target
> - It creates each skill directory and then calls `fs.cpSync` on that
same directory with `force: false` and `errorOnExist: true`
> - Node 24 rejects this with `ERR_FS_CP_EEXIST`, so every Grok run over
SSH fails with "Could not prepare Grok SSH runtime assets"
> - This pull request copies the contents of each skill into the new
empty directory
> - The benefit is that Grok SSH runs work again and the shared CI test
groups go green on master and on open PRs

## Linked Issues or Issue Description

Refs #22078

**What happened?**
Every Grok run on an SSH target fails before it starts. The error is
"Could not prepare Grok SSH runtime assets". The script on the target
fails with `SystemError [ERR_FS_CP_EEXIST]: Target already exists: cp
returned EEXIST (.../.claude/skills/selected already exists)`.

**Steps to reproduce**
1. Use Node 24.
2. Run `pnpm --filter @paperclipai/adapter-grok-local exec vitest run
src/server/remote-project-assets.test.ts`.
3. The "existing", "new" and "changed" cases fail.

**Expected behavior**
The skills are copied into `.claude/skills/<name>`, and the existing
project files stay safe.

**Impact**
CI fails on master and on unrelated open PRs:
- `ci / General tests (workspaces-b)`, in
`remote-project-assets.test.ts`
- the server group that runs `ssh-remote-workspace.integration.test.ts >
runs an assigned grok_local-cli task through heartbeat over SSH`

## What Changed

- `packages/adapters/grok-local/src/server/remote-project-assets.ts`:
after the script creates a skill directory, it now copies each child of
the source skill into that directory. Before, it copied the skill
directory onto itself. The copy keeps `force: false` and `errorOnExist:
true`, so it still does not overwrite files.

## Verification

- Red: on `origin/master` with Node v24.22.3,
`remote-project-assets.test.ts` fails 3 of 4 cases with
`ERR_FS_CP_EEXIST`. I saw this error in the script's stderr.
- Green: with this change, `vitest run src/server` in
`packages/adapters/grok-local` passes 137 tests in 9 files, and all 4
cases of `remote-project-assets.test.ts` pass.
- I could not run the SSH integration test locally. It needs a real SSH
server, so it is skipped here. CI runs it.

## Risks

Low risk. The change affects only the copy step for each new skill
directory. Cleanup and the safety checks for symlinks and paths do not
change. The script creates the target directory just before the copy, so
the directory is empty.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, test runs).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

The existing `remote-project-assets.test.ts` cases already cover this
bug: they fail before the fix and pass after it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 16:30:51 -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>
canary/v2026.1119.0-canary.829600
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
52cf30f131 test(release-smoke): follow onboarding into the standing chat (#22259)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The release workflow runs a Docker onboarding smoke on the real npm
artifact before it publishes a nightly or beta
> - #22077 changed onboarding. "Get started" now opens the lead's
standing chat. It does not create a first task or project
> - That PR updated the e2e tests, but it did not update the release
smoke
> - The smoke still expects an `/issues/` landing, so every nightly
smoke fails, and no nightly can publish
> - This pull request changes the smoke to assert the new chat-first
contract
> - The benefit is that the nightly lane can publish again, and the
smoke still guards the first-run experience

## Linked Issues or Issue Description

Refs #22077

**What happened?**
The release smoke `docker-auth-onboarding.spec.ts` fails at
`expect(page).toHaveURL(/\/issues\//)`. The page is on
`/<prefix>/chats/<agent id>`. The failure occurs on the first attempt
and on the retry. The scheduled nightly on 2026-11-18 and a dispatched
nightly for `2026.1118.0-canary.828200` both failed at this step.

**Steps to reproduce**
1. Run the release workflow with `channel=nightly` on a canary that
contains #22077.
2. Look at the `smoke_nightly / smoke` job.

**Expected behavior**
The smoke follows onboarding into the chat and passes when the artifact
works.

## What Changed

- Expect the launch to land on `/chats/<lead agent id>`, not on
`/issues/`.
- Assert that the task list and the project list are empty after launch.
- Assert that exactly one chat exists, with `originKind:
"onboarding_chat"`, no project, and the lead as `conversationAgentId`.
- Assert that the chat composer renders.
- Replace the old "no run" check. Now the smoke polls until the live
welcome run is queued for the lead. The provider mock serves no
completions, so the smoke does not check the welcome text.
- Remove the `FIRST_TASK_TITLE` constant, because onboarding no longer
seeds a task.

## Verification

- `tsc --noEmit --strict` on the spec passes.
- I checked the asserted fields against
`server/src/services/onboarding-chat.ts`, `GET
/companies/:companyId/chats` and
`tests/e2e/conference-room-typing-intro.spec.ts`.
- Full check: the `Release Smoke` workflow (or a nightly dispatch after
merge) must pass the `smoke` job.

## Risks

- Low risk. The change is test-only.
- The welcome-run assertion depends on the UI requesting the welcome in
a visible headless tab. If that is not true in CI, the poll times out
after 30 seconds. Then remove or relax that one assertion.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use (shell, GitHub
CLI).

## 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
- [ ] 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 16:12:17 -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>
canary/v2026.1119.0-canary.829100
2026-11-18 17:43:29 -06:00
Devin FoleyandPaperclip d702f567bc fix(recovery): keep a task's lock while its run's executor still settles it (#22248)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When an agent's provider account recently reported a usage limit,
Paperclip holds new work instead of starting a run that would fail the
same way. The provider limit wait cancels the run, then schedules a
retry at the expected reset, and the retry takes over the task's
execution lock
> - The cancellation and the retry are two separate writes. Cancelling
the run wakes task recovery for that task, and its stale-lock sweep
treats a cancelled run's lock as stale and clears it
> - When the sweep wins that race, the retry scheduler finds the lock
gone and refuses to schedule ("Subscription retry suppressed because the
task execution lock changed"). The wait then releases the task, and
stranded-work recovery escalates it to a person with a Retry button
> - The stranded-work reconciler already waits while a terminal run's
own executor is still settling it (`terminalRunSettlingUntil`). The
stale-lock sweep did not
> - This pull request makes the stale-lock sweep wait for the same
executor before it clears an open task's lock, and look again at the
executor's deadline
> - The benefit is that a task waiting for a provider usage limit
resumes by itself at the reset, instead of stopping on "Couldn't finish
this attempt" until someone presses Retry

## Linked Issues or Issue Description

Refs #19246, which added the provider usage limit wait.

**What happened?**
An agent's provider account hit a usage limit. A task's next wake was
held for the reset: its run was cancelled with `provider_limit_wait`.
About 200 ms later the stale-lock sweep cleared the task's execution
lock, because the run was now cancelled. The wait then tried to schedule
its retry, found the lock gone, and released the task. The continuation
that followed hit the same race. After two lost retries, stranded-work
recovery blocked the task and asked for Retry.

On one instance, 80 of about 600 provider-limit waits in two days lost
their retry this way, across 43 tasks. 15 of those tasks were blocked
behind a Retry button.

**Steps to reproduce**
1. Give an agent a recent provider rate-limit failure with no reported
reset.
2. Wake the agent on an assigned task.
3. Let task recovery sweep the task's locks between the cancellation and
the retry (the new integration test does this from the cancellation
write).

**Expected behavior**
The task keeps its lock for a retry scheduled at the reset.

**Actual behavior**
The sweep clears the lock, no retry is scheduled, and the task waits for
a manual Retry.

## What Changed

- `recovery/service.ts`: `sweepStaleIssueLocks` keeps an open task's
lock while a run that holds it is still being settled by its executor,
using the existing `terminalRunSettlingUntil`. That is a live execution
in this process, or an unexpired controller lease in another one. The
sweep reports the deadline through `onDeferredDeadline`, so it looks
again once the executor is done. A closed task's lock is still cleared
at once.
- Tests:
- The stale-lock sweep keeps an open task's lock while the executor is
live, and clears it once the executor is gone. A done task's lock is
cleared either way.
- A provider-limit wait whose cancellation is swept straight away still
schedules its retry, and the retry holds the task's lock.

## Verification

- `npx vitest run` on the new cases: pass. Both fail without the source
change; the integration test then reproduces the incident (the sweep
clears the lock and no retry is scheduled).
- `npx vitest run` on 58 related server test files (stale-lock sweep,
stranded and assigned-work recovery, provider limit wait, native resume
locks, retry admission, recovery hints): all pass, except 6 cases in
`runtime-selection.test.ts` that read a skill file from a fixed local
path. They fail the same way on master on this machine.
- `npx tsc --noEmit` passes for the server.

## Risks

- Low. The sweep waits only while the run's executor is provably still
running: a live execution in this process, or another process's
unexpired controller lease. A crashed executor has neither, so the sweep
clears the lock as before.
- An executor that keeps running after its run is terminal now delays
the sweep's backstop clear of an open task until it finishes. The
executor releases or hands off the lock itself when it finishes, and the
stranded-work reconciler already waits for the same executor.

## 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 15:39:14 -08:00
DottaandClaude Opus 5.5 28bdb4d778 feat(cloud): migrate durable data online and name volume-free config blockers (#22240)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosted Paperclip servers can move from a server with a volume to a
volume-free server, which allows deploys without downtime
> - A server with history can move online only after its durable data is
off the local disk
> - Today only an offline maintenance process moves that data, so each
existing server takes an outage of many minutes
> - Most data owners already work safely while the server keeps serving,
but nothing drives them online
> - This pull request adds a signed, bounded pass that drives those
owners online and reports progress, and it names configuration blockers
> - The benefit is that existing servers can move to volume-free with no
maintenance window

## Linked Issues or Issue Description

**What existing behavior does this improve?**
An existing volume-backed server can move to volume-free only through
offline maintenance, because only the offline process migrates its local
data.

**Subsystem affected**
Server: ephemeral enrollment, durable data owners (agent files, skill
packages and installations, runtime skill assets, native harness backups
and controllers), Cloud control endpoints.

**Current behavior**
- Online preparation refuses while local data remains, and no online
path moves that data.
- When the volume-free configuration is incomplete, preparation fails
with a server error that does not say why.

**Proposed behavior**
- `POST /api/instance/ephemeral-enrollment/migrate` (Cloud control
action `ephemeral-enrollment:migrate`) runs one pass with a 60-second
budget. The pass drives the online-safe owners, defers items that are
busy, and returns counts, deferral reasons and fresh eligibility.
- Preparation and the eligibility read report an incomplete
configuration as a named blocker: `volume_free_storage_flags_required`,
`volume_free_master_key_required`, `volume_free_decision_key_required`,
`volume_free_database_listener_required` or
`volume_free_configuration_required`. Preparation returns 409 with these
blockers.

**Reason and benefit**
Cloud can call the pass until a server is eligible, and then move it
online with no outage.

**Breaking changes**
None. The offline maintenance behavior is unchanged.

## What Changed

- New `services/online-durable-data-migration.ts`. The pass:
- requires S3 storage and `PAPERCLIP_DURABLE_AGENT_FILES=true`, so the
server does not keep creating local data;
- runs these owners in order, with live writers: `migrateAgentFiles`
(`writersStopped: false`), the local skill object copy, skill snapshots
and versions, skill installations, runtime skill assets, and the native
harness and controller prestage;
  - stops between pages when the budget is spent;
  - runs one pass at a time in each process.
- `skill-package-storage-migration.ts`: a new `online` mode. In this
mode a row that another owner holds is skipped and counted as `busy`.
The row claim and the publication already use compare-and-swap. The
offline mode is unchanged and still fails closed on a busy row.
- `services/ephemeral-enrollment.ts`: a configuration check maps the
volume-free contract errors to blocker codes. Preparation and the
eligibility read both use this check.
- `routes/ephemeral-enrollment.ts`, `middleware/cloud-control.ts`,
`services/cloud-runtime-identity.ts`: the new route and action. The
route accepts only an empty body.

## Verification

- `npx vitest run src/routes/ephemeral-enrollment.test.ts
src/services/ephemeral-enrollment.test.ts
src/services/online-durable-data-migration.test.ts
src/services/skill-package-storage-migration.test.ts
src/__tests__/openapi-routes.test.ts
src/services/cloud-runtime-identity.test.ts`: 102/102 pass.
- New tests:
- the pass drives every owner with live writers, aggregates counts and
deferrals, and reports eligibility;
  - the pass does nothing without S3 or durable agent files;
  - the pass stops at the budget;
  - one pass runs at a time;
- the skill object copy refuses outside maintenance unless the mode is
online, skips a busy row online, and still fails closed offline;
- each missing setting becomes a named blocker in preparation and in the
eligibility read;
- the migrate route accepts only a signed migrate assertion and an empty
body.
- `tsc --noEmit` reports no errors in the touched files. A full local
`pnpm verify` needs the Runner build, so CI covers it.

## Risks

- The pass runs real migrations while the server serves. Each owner
keeps its own locks and compare-and-swap rules. Busy items are deferred,
not forced. The budget limits each call.
- The skill object copy can now run online. It copies immutable objects,
verifies the hashes, and publishes only if the row did not change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, 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 17:36:30 -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
85a1e5f940 docs(release): canonicalize stable notes for v2026.1117.0 (#22247)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The release process promotes a soaked beta to stable and publishes
the curated notes as the GitHub Release body
> - After the publish, the notes must live at
`releases/v<stable-version>.md` on `master`. That path is the canonical
location that the website changelog and the next release notes use
> - Stable `v2026.1117.0` was published on 2026-11-18 from beta
`2026.1110.0-beta.0`, through the candidate branch
`candidate/release-2026.1117.0` (the beta source plus three test-only
cherry-picks and the notes file)
> - Because the notes resolved from the source tree
(`notes_mode=source_tree`), the workflow's `canonicalize_stable_notes`
job is skipped by design (it runs only for `master_beta`), so no
canonicalize branch was pushed
> - This pull request does by hand what that job does: it renames the
beta notes file on `master` to the stable path. It changes no content
> - The benefit is that `releases/v2026.1117.0.md` exists on `master`
and is byte-identical to the published GitHub Release body

## Linked Issues or Issue Description

Refs #22094
Refs #19770

**Issue type**

Missing content

**Where is the issue?**

`releases/` on `master`. The stable notes for `v2026.1117.0` are only at
the beta path `releases/beta/v2026.1110.0-beta.0.md`. The canonical path
`releases/v2026.1117.0.md` does not exist on `master`.

**What's wrong?**

The GitHub Release
https://github.com/paperclipai/paperclip/releases/tag/v2026.1117.0 is
published. The website changelog sync reads `releases/v2026.1117.0.md`
on `master`, so the changelog page for this release cannot appear until
this rename is merged.

**Suggested fix**

Rename the beta notes file to the stable path with no content change,
the same step the workflow job performs in `master_beta` mode.

## What Changed

- `releases/beta/v2026.1110.0-beta.0.md` is renamed to
`releases/v2026.1117.0.md`. Git reports a 100% rename
- No line of the file changes. The blob is
`dff612e41f915a5a2d9f3e572142e2fee56068a8`, the same blob as
`releases/v2026.1117.0.md` at the release source commit
`c0f132898d2a2677312d8c72096187b27a3d9a38` (tag `v2026.1117.0`)
- This pull request does not change the release workflow

## Verification

- `git diff --numstat -M origin/master
release-notes/v2026.1117.0-canonicalize` shows one renamed file with 0
insertions and 0 deletions
- `git rev-parse
release-notes/v2026.1117.0-canonicalize:releases/v2026.1117.0.md` prints
`dff612e41f915a5a2d9f3e572142e2fee56068a8`
- `git rev-parse v2026.1117.0:releases/v2026.1117.0.md` prints the same
blob
- The raw `body` field of `gh api
repos/paperclipai/paperclip/releases/tags/v2026.1117.0`, compared with
`cmp` against the file, reports no difference
- After merge,
https://github.com/paperclipai/paperclip/blob/master/releases/v2026.1117.0.md
should return 200 and the old beta path 404

## Risks

- Low risk: one markdown file moves and no content changes

## Model Used

- Claude (Anthropic), model ID `claude-opus-5-5` (Claude Opus 5.5), tool
use via 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: devinfoley <139239+devinfoley@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:26:53 -08:00
DottaandClaude Opus 5.5 d1ca0cc218 fix(native): stop retrying a run that filled its sandbox disk (#22239)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Native agent runs execute in a managed sandbox with a fixed disk
size
> - An agent can fill that disk. The runner then exits with "No space
left on device". The disk reserve restarts the runner, but the turn in
progress can still be lost, and the run fails
> - The run failure did not carry the full-disk fact. The run was
classified as a generic provider or runner failure. Automatic recovery
then started the same work on a fresh sandbox of the same size, which
filled the disk again. After three attempts the task stopped in
"Recovery needed" with no useful explanation
> - This pull request names the cause `sandbox_disk_full` when the
runner reported a full disk during the run, and stops automatic retries
for that cause
> - The benefit is that Paperclip no longer spends sandboxes and time on
retries that cannot succeed, and the task tells the user what to do in
plain language

## Linked Issues or Issue Description

**What happened?**
A native run in a managed sandbox filled the 10 GiB disk. The runner
exited with "No space left on device (os error 28)". The runner was
restored, but the in-flight turn was lost and the run failed as
`native_provider_terminal_failed`. Automatic recovery repeated the same
work on a fresh sandbox of the same size three times. Each attempt
filled the disk again. The task ended in "Recovery needed" with an
unrelated cause.

**Expected behavior**
When a run ends because its sandbox disk is full, the run failure names
that cause. Automatic recovery does not repeat the same work on a
sandbox of the same size. The task shows a plain-language explanation
and a working Retry.

**Steps to reproduce**
1. Run a native agent task in a managed sandbox whose work installs more
than the free disk space.
2. Wait until the runner exits with "No space left on device".
3. See the run fail as a generic provider failure, and see automatic
retries start fresh sandboxes that fail the same way.

**Relevant logs or output**
`paperclip-runner` exited with "No space left on device (os error 28)".
The run then failed with `provider_turn_lost_on_restore`, classified as
`native_provider_terminal_failed`.

Refs #22068 (disk reserve that restarts the runner). Refs #22235
(continues a turn that a runner restore lost, once, in the same
sandbox). This PR covers the case where the run still ends.

## What Changed

- Server: each run's diagnostic lease now records when a runner
diagnostic reports a full disk (`ENOSPC`, `EDQUOT`, "No space left on
device", "Disk quota exceeded"). The runner's exit detail already
reaches the server as a diagnostic, so no runner change is needed. The
fact belongs to that run's diagnostic epoch only. A later run on the
same warm session, or a diagnostic after the epoch retires, does not see
it.
- Server: native failure classification returns `sandbox_disk_full` when
either (a) the run's lease saw a full-disk report, or (b) the error
chain carries the runner's existing `sandbox_disk_full` launch code (a
relaunch that cannot stage on the full disk). A fixed list of failures
keeps its own meaning: permission, approval, usage limit, model,
runtime, integrity, cleanup quarantine, ownership, saved-state and
admission failures.
- Server: `sandbox_disk_full` is a permanent native failure. The run
does not take another same-run attempt. Native safe replacement does not
pick it up, because it is not one of its failure codes. The task becomes
blocked with a board-owned recovery action and a plain-language next
action.
- Server: the bounded retry scheduler (`scheduleBoundedRetryForRun`)
refuses `sandbox_disk_full`. It does not schedule a `transient_failure`
retry on a fresh sandbox of the same size.
- UI: the task chat shows "Disk full" and a plain explanation instead of
the raw failure code.
- Retry stays available. `sandbox_disk_full` is not a reconciliation
cause, so the board's Retry starts a new run when the user chooses.

## Verification

- Red before the fix (captured on the unfixed code):
- `heartbeat-retry-scheduling.test.ts` "does not repeat a run that
filled its sandbox disk on a fresh sandbox of the same size": expected
`not_scheduled`, received `scheduled`.
- `native-sandbox-disk-full.test.ts` "names the full disk and stops
instead of retrying the same work": expected `sandbox_disk_full`,
received `native_provider_terminal_failed`.
- `native-sandbox-disk-full.test.ts` "names the full disk when the
runner could not be relaunched on it": expected `sandbox_disk_full`,
received `native_session_interrupted`.
- Green after the fix:
- `cd server && npx vitest run
src/services/native-runtime/native-sandbox-disk-full.test.ts
src/__tests__/heartbeat-retry-scheduling.test.ts
src/services/native-runtime/remote-runner-disk-reserve.test.ts` (90
passed).
- `cd ui && npx vitest run src/components/TaskChatThread.test.tsx` (426
passed).
- `cd server && npx vitest run
src/services/native-runtime/native-session-executor.test.ts
src/services/native-runtime/native-session-diagnostics.test.ts`.
- Safety cases in the tests:
- A runner that exited for another reason still gets its bounded retry.
- A turn lost on restore without a full-disk report keeps
`native_provider_terminal_failed`.
- Integrity and approval failures keep their codes when a full disk was
reported.
- A full-disk report belongs only to its own run's diagnostic epoch; run
B on the same session does not see run A's report.
- After a full-disk report, other runner and provider loss codes
(session.open timeout, initialize timeout, protocol error, process
status failure) also become `sandbox_disk_full`.
- Worst-case automatic run starts per hour across a company: before,
each disk-full task started up to 3 automatic runs, each on a fresh
sandbox (3 × the number of affected tasks). After, a disk-full failure
starts 0 automatic runs. Only a person's Retry starts a new run. Real
transient failures keep their existing bounded lanes, so their worst
case is unchanged.
- Not run locally: the full server suite, the full typecheck and build.
Required CI covers them.
- Not verified live on staging yet. A live check needs a run that fills
its sandbox disk after this change deploys.

## Risks

- A run whose runner reported a full disk, and which later fails with a
runner or provider loss for an unrelated reason, is now labeled
`sandbox_disk_full` and is not retried automatically. The board's Retry
still works. This is the safer error: a full disk is the most likely
cause, and an automatic retry would repeat the same disk use.
- The full-disk report lives on the run's in-memory diagnostic lease. A
server restart between the report and the failure loses it, and the run
falls back to the previous classification. That is the previous
behavior, not a new failure.
- Low risk otherwise. No schema or API 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

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`) in 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 23:19:12 +00:00
DottaandClaude Opus 5.5 07d9316218 fix: restore master's typecheck and runner SDK input pin (#22242)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - #22235 added a runner regression test for a turn lost to a mid-run
`runnerd` restore
> - That test reads `startTurn.mock` inside the initializer of
`startTurn` itself
> - The CI test-program typecheck rejects this with TS7022 and TS7024,
so master fails "Typecheck + Release Registry"
> - This pull request counts calls in a local variable instead
> - The benefit is that master typechecks again, and the test behaves
exactly as before

## Linked Issues or Issue Description

Refs #22235, Refs #22234

**What happened?**
After #22235 merged, `ci / Typecheck + Release Registry` failed on
`packages/paperclip-runner/src/native-session-runtime.test.ts(724)` with
TS7022 ("'startTurn' implicitly has type 'any'...") and TS7024.

**Steps to reproduce**
1. Run the CI typecheck lane (`typecheck test programs`) on master after
#22235.
2. See TS7022 and TS7024 at line 724 of the test.

**Expected behavior**
The test program typechecks.

## What Changed

- The `startTurn` mock in the new test uses a local call counter instead
of reading its own `mock.calls`.
- `tests/runner-e2e/source-sdk-public-inputs.json`: refresh the pin for
`packages/shared/src/app-definitions/github.json`, which #22234 changed
without updating it. The Runner support suite fails on master without
this.

## Verification

- `npx tsc -p packages/paperclip-runner/tsconfig.test.json --noEmit`
reports no errors in the test file.
- `npx vitest run src/native-session-runtime.test.ts` in
`packages/paperclip-runner`: 301/301 pass.

## Risks

- Low risk. This changes a test and regenerates a pin with the
repository script (`node tests/runner-e2e/source-sdk-public-inputs.mjs
<sha> --write`). `source-sdk-public-inputs.test.mjs`: 13/13 pass.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 16:49:12 -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
Devin FoleyandPaperclip e4b119440e Show live provider reset countdowns in the viewer's timezone (#22225)
## Thinking Path

> - Paperclip manages agents and their assigned work.
> - Provider usage limits can hold that work until a reset deadline.
> - Saved wait messages expose raw timestamps, and the usage popover
shows a short weekday clock.
> - People need the remaining wait and the exact deadline in their
current timezone.
> - This pull request formats both views in the browser and updates the
countdown live.
> - The browser uses its timezone while stored messages and retry
deadlines stay unchanged.

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Provider usage limit messages and the agent usage-limit property and
popover.

**Subsystem affected**
UI presentation of provider usage limits, task notices, run details, log
events, and recovery actions.

**Current behavior**
Wait messages print `2026-11-18T20:17:34.353Z`. The usage popover shows
a short clock such as `Thu 23:00`. Neither gives a live relative
countdown. If the provider did not report a reset, the scheduler uses
the recorded failure time plus one hour.

**Proposed behavior**
A Pacific-time viewer sees `in 44 minutes (Nov 18, 2026, 12:17 PM PST)`.
The relative part counts down while the tab is visible. The usage
property and popover show the same local deadline. Expired usage windows
clear through the existing summary rules.

**Reason and benefit**
People can see how long remains without converting a timestamp or
refreshing the page. The date conversion handles daylight saving time
and local date changes.

**Breaking changes**
Displayed text and popover layout change. Stored messages, API payloads,
error codes, provider checks, and retry deadlines keep their contracts.

## What Changed

- Add an optional timezone label to the existing `formatDateTime`
helper. Existing callers keep their output.
- Share relative and exact local time formatting between provider-limit
messages and the usage popover. Unrelated text and invalid timestamps
stay intact.
- Reuse the existing shared one-second ticker. Countdown updates pause
in hidden tabs, catch up when shown, and stop at the deadline or on
unmount. No API polling is added.
- Keep timer-driven message rendering separate from large parent pages.
Hidden task-marker details do not subscribe until opened.
- Update task notices, agent run errors in both UI shells, log events,
and provider-limit next actions.
- Update the usage-limit trigger and every window in its popover. Reset
details wrap below the percentage row. The reported timestamp includes
its timezone. Explicit clocks remain fixed for stories.

## Verification

Tested source: `ef79ce40b170db89a6b831162c72d6446cd9492d`. Local checks
ran with the same file contents on macOS arm64, Node 25.6.1, and pnpm
9.15.4.

- From `ui/`: `pnpm exec vitest run
src/lib/provider-limit-message.test.ts src/lib/utils.date-time.test.ts
src/components/ProviderLimitMessage.test.tsx
src/hooks/useSecondTick.test.tsx
src/components/AgentRateLimitGauge.test.tsx
src/components/task-chat/TaskChatMarker.test.tsx
src/components/task-chat/TaskChatSystemNotice.test.tsx
src/components/IssueRunLedger.test.tsx
src/components/IssueRecoveryActionCard.test.tsx
src/components/StalledDependencyNotice.test.tsx
src/pages/AgentDetail.log-visibility.test.tsx
src/pages/AgentDetail.log-resilience.test.tsx` — 176 tests passed across
12 files.
- From `ui/`: `pnpm run typecheck` — passed, including Storybook catalog
generation.
- From the repository root: `pnpm check:token-gates` and `git diff
--check` — passed.
- Regression proof: four live-message cases failed against static
rendering. Four usage-popover cases failed against the old clock. Both
suites passed after the changes.
- Fake-clock tests prove `44 minutes` becomes `43 minutes` without a
page refresh or parent render. Other cases cover seconds near the
deadline, one shared timer, hidden-tab pause and catch-up, expiry, and
cleanup.
- Timezone cases cover Pacific, India, and New Zealand timezones, a
local date rollover, and daylight saving time. Task notice cases cover
both presentations. Usage-popover cases cover Claude and Codex.
- Local setup required a non-frozen install because the base lockfile
lacked two AWS SDK dependencies from the server manifest. No dependency
or lockfile change is included.
- Final CI: [workflow attempt
4](https://github.com/paperclipai/paperclip/actions/runs/44384225521/attempts/4)
succeeded on `ef79ce40b170db89a6b831162c72d6446cd9492d`. All 54
successful checks are green, including the applicable typecheck, build,
server tests, Runner checks, and all eight end-to-end shards. Optional
jobs skipped by the CI plan remain skipped.
- Recovery record: [Canary attempt
1](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135085343566),
[attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135097010510),
and [attempt
3](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135100921795)
ended with runner shutdown signals at 19:56:15, 20:12:55, and 20:19:18
UTC. The aggregate verification failures reflected that canary result.
No source changed between attempts. The [fourth Canary Dry
Run](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135105826026)
and [aggregate
verification](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135110708013)
passed.
- Greptile reviewed the final commit at 5/5 with no actionable findings
and no unresolved review threads. GitHub reports the branch mergeable
with a clean merge state.
- Full local repository checks and manual browser acceptance were not
run. CI supplied broad coverage on the final revision. The local popover
tests exercise its content and clock with mocked popover primitives.

## Risks

- Low risk. This changes UI presentation only. No migration or scheduler
change is required.
- The ticker updates visible future countdowns once per second. It makes
no provider request and does not certify that provider capacity has
returned.
- Message recognition uses the existing provider-limit wording and ISO
timestamps. Unrecognized messages retain their text.
- Local timezone abbreviations can differ by browser locale data. Time
conversion uses the browser's timezone rules.

## Model Used

- OpenAI Codex, `gpt-6.1-sol`, with xhigh reasoning effort, repository
inspection, code edits, and 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
- [x] I have described the issue in-PR with the enhancement template
fields
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run the focused tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] The code, tests, and this description document the changed output
- [x] I have considered and documented the risks
- [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 14:19:17 -08:00
DottaandClaude Opus 5.5 d668eeb660 fix(runner): keep Claude MCP bearer tokens out of process arguments (#22206)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - The runner starts Claude through ACPX and the Claude ACP agent.
> - The runner gives Claude HTTP MCP servers: the task tool bridge and hosted connectors. Each server has a bearer token.
> - The Claude Agent SDK writes these servers, with their headers, into the inline `--mcp-config` argument of the Claude CLI.
> - Thus a `ps aux` or `ps -ef` command in the sandbox shows the bearer tokens. Tool logs then keep the tokens.
> - This pull request sends a `${VAR}` reference in the header. The token goes into the launch environment of the agent.
> - The benefit is that process lists do not show MCP bearer tokens.

## Linked Issues or Issue Description

**What happened?**
An agent ran `ps aux` in its sandbox. The output showed the Claude CLI process with an `--mcp-config` argument. That argument had an `Authorization: Bearer <token>` header for each HTTP MCP server. The tool log kept the full output.

**What did you expect to happen?**
Process arguments must not contain credentials. A process list must not show MCP bearer tokens.

**Steps to reproduce**
1. Start a Claude agent on the runner with the task tool bridge or a hosted connector.
2. In the agent, run `ps -ef`.
3. Look at the Claude CLI line. The `--mcp-config` JSON contains `"Authorization":"Bearer ..."`.

**Root cause**
`openQualifiedAcpxRuntime` sent the literal `Bearer <token>` header in the ACP `mcpServers` list. The Claude ACP agent gives this list to the Claude Agent SDK. The SDK always serializes it into `--mcp-config <json>` on the CLI command line.

## What Changed

- For the Claude ACPX profile, each HTTP MCP header now has the value `Bearer ${PAPERCLIP_ACPX_MCP_BEARER_<n>}`.
- The runner puts each token in the Claude launch environment under the same name. Claude Code expands `${VAR}` in `--mcp-config` when it connects to the server.
- Other ACPX agents keep the literal header. Their CLIs do not have a known `${VAR}` expansion.
- Added a regression test. Updated one exact launch-environment assertion for the new variable.

## Verification

- Failing before the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter.test.ts -t "MCP bearer tokens out of the CLI argv"` (in `packages/paperclip-runner`). It failed with `expected '[{"type":"http","name":"paperclip",…' not to contain 'bridge-secret'`. The projected header had the literal synthetic token.
- Passing after the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter` — 7 files, 136 tests passed.
- Manual check of the expansion: I ran the pinned Claude CLI (agent SDK 0.3.286) with `--mcp-config` and a header `Bearer ${SYNTH_MCP_BEARER}` against a local HTTP server. The server got the expanded synthetic value.
- `tsc --noEmit -p packages/paperclip-runner`: no new errors. The only errors are in `src/eval/workflow-harness.ts` and occur on `master` too, because my local install did not include the eval kernel package.
- The full `src/drivers/acpx/` folder has other failures in this sandbox (`EACCES` on `/proc/self/fd` spawn, directory fsync). The same failures occur on `master` without this change.

## Risks

- Medium-low risk. If a future Claude CLI stops the `${VAR}` expansion in `--mcp-config`, MCP calls fail authentication. They do not leak the token. The regression test pins the header shape.
- The token is now in the Claude process environment. Only the same user can read `/proc/<pid>/environ`. Other credentials are already in this environment. Shell tools that Claude starts also inherit the environment, so `env` output can still show the token. Log redaction must continue to cover bearer values.
- Tokens that already appeared in logs are not revoked by this change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code execution.

## Checklist

- [x] I have included a thinking path that traces from project context to this change
- [x] I have specified the model used (with version and capability details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before requesting merge

Related: #13572 removes bearer tokens from curl arguments in the agent helper scripts. This pull request covers the Claude CLI MCP configuration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)



Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1118.0-canary.828200 nightly/v2026.1119.0-nightly.0
2026-11-18 15:58:46 -06:00
DottaandClaude Opus 5.5 bb258a5429 fix(connections): explain failed app sign-ins and guide GitHub app install (#22234)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents can ask a person to connect an app, such as GitHub, through a
sign-in window
> - When that sign-in fails, the server knows the reason and records it
in the activity log
> - The sign-in window tells the opener only "failed", so the person
sees "Authorization did not complete" for every cause
> - People cannot fix the problem themselves, and support cannot help
without reading server data
> - This pull request sends the safe failure code to the opener and
shows plain copy for the common causes
> - The benefit is that a person knows what to do next, such as to
finish faster or to stay in the same session

## Linked Issues or Issue Description

**What happened?**
A user tried to connect GitHub from an agent request. The dialog showed
"GitHub couldn't connect. Authorization did not complete. Try again when
you're ready." The same text shows for every failure cause.

**Expected behavior**
The dialog should tell the user why sign-in failed and what to do next.

**Steps to reproduce**
1. Start an app connection from an agent request.
2. Let the sign-in take longer than the state lifetime, or finish it in
a different Paperclip session.
3. See the generic "Authorization did not complete" message.

**Paperclip version or commit**
`master` at 84a529df4f.

**Deployment mode**
Paperclip Cloud. The connection-intent sign-in path is the same in
self-hosted deployments.

## What Changed

- The connection-intent sign-in page now posts a `code` field with a
`failed` outcome. Only codes that match `^[a-z][a-z0-9_]{0,63}$` are
sent. Connected and declined outcomes send no code.
- Both OAuth callback catch blocks pass their failure code to that page.
- OAuth state errors now carry codes: `oauth_state_expired`,
`oauth_state_missing` and `oauth_session_mismatch`.
- The setup flow maps common codes to plain copy. Unknown codes keep the
old generic text, and raw codes never show to the user.
- The managed-connector callback now records `tool_app.oauth_failed`
with the failure code. Before, it answered 200 and recorded nothing.
- A callback whose state is already gone now answers an HTML request
with a page that posts `oauth_state_missing`. The dialog accepts it only
from its own active sign-in window.
- GitHub: before sign-in, the setup explains that Paperclip connects
through the Paperclip for GitHub app and which account to install it on.
- GitHub: when sign-in finds no usable installation, the sign-in window
passes the GitHub install and manage links (github.com only) to the
dialog. The dialog shows "Install Paperclip on GitHub" and "Manage
repositories on GitHub" next to "Try again".

## Verification

- `server`: `npx vitest run
src/routes/tool-access-connection-intent.test.ts
src/__tests__/generic-mcp-connection.test.ts` (126 passed). A new test
checks that a safe code is posted, an unsafe code is dropped, and a
connected outcome has no code.
- `server`: `npx vitest run
src/__tests__/tool-access-oauth-protocol.integration.test.ts -t "missing
sign-in state"` covers the missing-state page on both callbacks.
- `ui`: `npx vitest run src/features/connections/` (130 passed). Tests
cover the GitHub install links, which drop non-github.com links, and
missing-state messages from an old window.
- `ui`: earlier run `npx vitest run
src/features/connections/ConnectionSetupFlow.oauth.test.ts` (21 passed).
New tests check the copy for expired and cross-session sign-in, and that
unknown codes show the generic text.

## Risks

- Low risk. The postMessage adds one optional field. Old openers ignore
it.
- The state errors now include `details.code`. The status codes and
messages do not change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [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:56:16 -06:00
DottaandClaude Opus 5.5 06750cb18e fix(runner): continue a turn lost to a mid-run runnerd restore (#22235)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents in a managed sandbox run under the Paperclip runner
(`runnerd`). When `runnerd` exits mid-run, the transport relaunches it
in the same execution, and the runner restores the same conversation
> - An agent can fill the sandbox disk with its own work. `runnerd` then
cannot write its state and exits. #22068 added a disk reserve so the
relaunch succeeds. Its stated goal was that "the agent's turn can
continue and see the full disk"
> - The relaunch now works, but the turn still dies. The runner reports
the in-flight turn as `provider_turn_lost_on_restore`. The runtime sends
its single same-conversation continuation only for a session recovered
at startup under a control-plane restart claim. A relaunch inside the
live execution has neither, so the run fails as
`native_provider_terminal_failed`
> - The generic transient retry then starts on a fresh sandbox, redoes
the same install, fills the disk again, and ends in board-owned
"Recovery needed"
> - This pull request lets the execution that started a turn send the
existing one-time continuation when the runner reports that same turn
lost on restore
> - The benefit is that the agent keeps its conversation and workspace
and sees the full disk in its own tools, instead of the run dying and
retrying into the same wall

## Linked Issues or Issue Description

Refs #22068

**What happened?**
On staging, two agent tasks on the Paperclip monorepo each failed on
every attempt (5 failed runs in total). Each run used a fresh managed
Daytona sandbox with 10 GiB of disk. The agent's own `df` showed `/` at
10G of 10G with 236K free. `node_modules` used 3.2G and
`.paperclip-runtime` used 6.1G: about 3.0G of provider pack and a 2.8G
pnpm store under the session data directory. `runnerd` exited with
`failed to create private durable state temporary file: No space left on
device (os error 28)`. The transport relaunched it in about 20 s, and
runnerd restored its durable session. Then the runner reported
`turn.failed {code: provider_turn_lost_on_restore, recoverable: true}`,
and the run failed as `native_provider_terminal_failed`. Retries on
fresh sandboxes hit the same failure. The tasks ended in "Recovery
needed" with `provider_failure_meaning_unverified`.

**Steps to reproduce**
1. Run an ACPX or Codex agent through `paperclip_runner` in a managed
sandbox.
2. Have the agent fill the disk during a turn, or end `runnerd` in any
other way mid-turn while the server keeps running.
3. The transport relaunches `runnerd`, and the runner reports the turn
as lost on restore.
4. The run fails instead of continuing the turn.

**Expected behavior**
The execution that started the turn sends one continuation turn in the
restored conversation, exactly as it does after a server restart. The
agent continues from its recorded progress and sees the full disk in its
tools.

**Environment**
Managed Daytona sandbox (fleet snapshot, 4 CPU, 8 GiB memory, 10 GiB
disk), `paperclip_runner` native runtime with Claude through ACPX.

## What Changed

- `packages/paperclip-runner/src/native-session-runtime.ts`: the
execution records the turn id of the turn it starts.
`resumeInterruptedTurn` now accepts two owners of a turn lost on
restore:
- a session recovered at startup with the control-plane restart claim,
for the checkpointed active turn (unchanged), or
- a session this execution opened itself, for the turn this execution
started (new).
- All other guards stay: one continuation per run, the provider
allowlist, no compaction or goal runs, no pending runtime requests, and
the snapshot must show that same turn as restart-interrupted.
- `native-session-runtime.test.ts`: a new regression for an ACPX session
that loses its own turn to a mid-execution `runnerd` restore, plus a
negative case for a lost turn this execution never started.

## Verification

- Red before the fix: `npx vitest run
src/native-session-runtime.test.ts` failed `continues its own turn once
when runnerd is restored mid-execution` with
`NativeProviderTerminalFailure: Provider turn failed`, the same failure
seen on staging.
- Green after the fix: `native-session-runtime.test.ts` and
`native-session-runtime.provider-turn.test.ts` pass (337/337). The
existing `requires the control plane restart claim` case still refuses a
recovered session without the claim.
- `pnpm verify` (affected selection): see the CI results on this PR.
- Live acceptance: after deploy, retry the affected staging tasks and
confirm that a mid-turn `runnerd` restore leads to one continuation turn
in the same sandbox instead of `native_provider_terminal_failed`.

## Risks

- **Second executor.** The continuation can start only from the
execution that opened the session and started the turn. It is not used
for a recovered or adopted session without a claim. It runs at most once
per run (`restartContinuationStarted`). The runner emits this code only
after it proves the old provider process ended.
- **Run starts.** This starts no new runs. It adds at most one turn to a
run that would otherwise fail and schedule a fresh-sandbox retry. During
a crash loop, `MAX_UNSTABLE_RUNNER_RESTORES` in the transport still
fails the transport.
- **Disk still full.** If the continuation fills the disk again, the
second lost turn finds `restartContinuationStarted` set, and the run
fails as it did before. The worst case is the current behavior.
- **Not in this PR.** Paperclip's own footprint (about 3G of provider
pack per sandbox, and a per-session pnpm store) and classifying a
disk-full failure so it does not retry into the same wall. Both are
follow-ups.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, browser, and a code-tracing subagent).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:55:16 -06: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 46e38e1387 fix(native): let the outgoing server checkpoint its idle warm session while its follow-up has not started (#21887)
**HOLD: do not merge until the coordinator confirms (merging resets the
zero-downtime gates).**

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A deploy swaps servers with an overlap. A warm agent session stays
with the outgoing server that ran its last turn.
> - When that turn finishes during the overlap, the outgoing server
saves its idle session and closes it. A checkpoint fence decides whether
the save is still allowed.
> - The task's follow-up run usually starts on the incoming server at
the same moment. It waits for the outgoing owner (#21774), and #21791
lets the outgoing server save while the follow-up is parked on it.
> - The fence still refused the save
(`native_runner_checkpoint_owner_lost`) in every other state of the same
unstarted follow-up. In release-swap waves the close then fails at least
once and retries, and the follow-up waits longer. If every attempt hits
such a window, the owner stays until the outgoing server stops, up to
the 510 s overlap. Speed is a requirement.
> - This pull request makes the fence accept the outgoing server's final
save in every state in which the follow-up has not started: no process,
no own process start, no own checkpoint, `attempt = 0`, same session. It
still refuses when the follow-up names another owner or has started.
> - The benefit is that the outgoing server closes its session on the
first attempt, and the follow-up continues at its next owner check.

## Linked Issues or Issue Description

Refs #21791, #21774, #21782

**What happened?**

Release-swap waves logged `idle warm native session close failed …
native_runner_checkpoint_owner_lost`. The close worked on a later
attempt. Two recent waves, traced with the wave's 2-second run samples:

| Wave | Outgoing run | Attempt | Follow-up at that moment | Old fence |
| --- | --- | --- | --- | --- |
| 13:48Z | `480c86e4` (finished 14:29:04.7) | 1, 14:29:07.7 |
`5396e5ab`, started 14:29:05.6 on the incoming server: `preparing`
(legacy, incoming boot) at 06.2, native `observed` with no owner at 08.2
| refused: a preparing follow-up was accepted only on the outgoing
server's own boot, and a native follow-up only when parked or re-claimed
with `waitingForOwner` |
| 15:58Z | `87de6f54` (finished 16:16:14.1) | 1, 16:16:19 | `2009f6bb`,
started 16:16:18.7: `preparing` (legacy, incoming boot) at 19.8 |
refused: foreign preparation |
| 15:58Z | `87de6f54` | 2, 16:16:27 | `2009f6bb`: native `observed`, no
owner from 21.8 to 25.8, owner stamped at 27.8 | refused: selected
follow-up before its first owner check, or a park or re-claim without
`waitingForOwner` |

In each case the follow-up was the task's current run and had no
process, no process-start event and no checkpoint rows. No successor
claim or stale epoch held the session: the outgoing server's own run had
committed and released its lease. The fence refused only because it did
not recognize these states of the same unstarted follow-up.

**Expected behavior**

The outgoing server saves and closes the session on the first attempt
while the follow-up is in any unstarted state. The follow-up then sees
the saved session at its owner check and continues without parking (or
within one recheck if it already parked).

**Steps to reproduce**

1. Run a warm native session on a remote sandbox, and let a run finish
on server A during a swap to server B.
2. Let B claim the follow-up right away.
3. While B prepares it, selects native execution, parks it, or re-claims
it, A saves and closes its idle session. The fence refuses the save.

**Paperclip version or commit**

master `f61b919701` (merged in). The waves ran on master builds without
this pull request.

## What Changed

- `native-runner-checkpoint.ts`: the parked-follow-up check is now
`unstartedSuccessorOfOwner`. It takes `FOR SHARE` on the follow-up's
finalization row (if any), then on its run row, in that order, inside a
savepoint. The claim and defer paths use the same order. If native
selection created the finalization row while the fence waited for the
run lock, the fence rolls the savepoint back, which releases the run
lock, and takes both locks again in the same order (at most twice). A
last statement then reads the current state again and accepts one of
these states:
- **Preparing on any server** (new): the run is still `legacy`,
`preparing`, on this task, has a live controller lease and no process,
and has no finalization row. Before, only the outgoing server's own boot
was accepted.
- **Selected, before its first owner check** (new): native, finalization
`observed`, `attempt = 0`, no lease, no failure, empty recovery history.
  - **Parked**: as before, but `waitingForOwner` may be absent.
- **Re-claimed**: as before (live `same_run_resume` claim by the current
controller), but `waitingForOwner` may be absent, as in claims from a
previous release.
- These conditions apply to every state and are unchanged: running; no
own process-start event; no own checkpoint rows. For the native states,
also: same company, task and native session; `attempt = 0`; no result;
no process, unless it is the identity inherited from the outgoing run
(`inheritedProcessIdentityRunId`). The fence still requires an accepted
result and no new work.
- A `waitingForOwner` that names another run or boot is still refused.
- `SAME_RUN_RESUME_DISPOSITION` moves to the leaf module
`same-run-resume-disposition.ts`. The fence no longer imports
`scheduled-resume-continuation.ts`, so the runner E2E server does not
load the executor and `@paperclipai/plugin-sdk` through it
(`server-startup-import-graph.test.ts`).
- The run-row share lock makes native selection (`runtime_selection`
locks the run `FOR UPDATE`) and process start wait for the save to
commit. A save that waited reads the committed state in its last
statement and is refused if the follow-up has started.
- Tests, real Postgres:
  - `native-controller-recovery.integration.test.ts`, new:
- The outgoing server saves and closes while the incoming server
prepares the follow-up.
    - Native selection of that follow-up waits for the save.
- A save that waited while native selection held the run lock and
created the coordinator is accepted (Greptile review).
- It saves and closes while the follow-up is selected but before its
owner check, also with an inherited process identity, and the
follow-up's check resolves at once.
- It saves and closes while the follow-up is parked or re-claimed
without `waitingForOwner`, including a claim entry in the previous
release's shape.
- Still refused, preparing: expired controller lease, `dispatching`, own
process, own process-start event, other task.
- Still refused, selected: own process, a process inherited from another
run, own process-start event, own checkpoint, other session, admitted
(`attempt = 1` with a lease).
    - The outgoing-server fixtures share one helper.
- `native-harness-backup-storage.integration.test.ts`: the harness
backup fence shares this check. A released owner whose follow-up is
still preparing on another server now replaces its selected backup.
`expired_preparation`, `dispatching_successor` and `foreign_native`
still keep the old backup.
- `native-runner-restart-recovery.integration.test.ts`: the
`foreign_preparation` early-retirement case now expects the save to
succeed. `expired_preparation`, `dispatching_successor`, `wrong_issue`,
`unclaimed_successor` (another session) and `foreign_native_preparation`
still expect a refusal.
- From the earlier commits of this pull request: the re-claimed state,
`sameRunResumeClaimEntry` recording `waitingForOwner`, the run-row lock
and the post-lock recheck.

## Verification

- Red/green for this round (only the fence source changed between runs):
- With the fence at `ed7227eeda` (this pull request before this round),
9 tests fail with `native_runner_checkpoint_owner_lost`: preparing close
(+ `foreign_preparation` ×2), native-selection ordering,
selected-before-check ×2, waiting-without-owner ×3. The 11 new refusal
cases pass both before and after.
- With the fence change:
`native-controller-recovery.integration.test.ts` and
`native-runner-restart-recovery.integration.test.ts` 306 passed, 14
skipped. `native-harness-backup-storage.integration.test.ts` 73 passed.
`scheduled-resume-continuation.test.ts`,
`native-runner-checkpoint-save.test.ts` and
`native-controller-recovery.integration.test.ts` 110 passed.
- Savepoint restart: the new waited-on-native-selection test fails with
`native_runner_checkpoint_owner_lost` without it, and passes with it.
- `tests/runner-e2e/server-startup-import-graph.test.ts` failed in CI at
`cc513d9434` (import path through `scheduled-resume-continuation.ts`).
It passes locally after the move.
- Earlier rounds (unchanged): red on master for the re-claimed close,
the process-start ordering and the claim ordering; red without the
run-row lock; red without the recheck.
- `tsc --noEmit` for `server` passes.
- `pnpm verify` (base `f61b919701`) selected 2842 of 3683 files, because
the checkpoint module has a wide import graph. The reusable job passed:
2 files, 12 tests. The fresh job was cut off locally (exit 144, no test
failure printed). Required CI supplies that coverage.
- `node scripts/agent-preflight.mjs` stops at `pnpm install
--frozen-lockfile`: on master, `server/package.json` lists
`posthog-node` (#22006) and the lockfile does not have it yet. CI
resolves the lockfile inline. Locally, dependencies were installed
without the frozen lockfile, and `pnpm-lock.yaml` was not committed.
- Not run: a release-swap wave. The coordinator runs the gates.

## Risks

- The fence is wider. It now accepts the outgoing server's final save
while the follow-up is in any state before it starts. The save needs an
accepted result and no new work. The follow-up must have no process
(except the identity inherited from this run), no process-start event,
no checkpoint of its own, and `attempt = 0`. A follow-up that names
another owner, holds an expired claim, has been admitted, or is in
another session is still refused.
- A follow-up that another server is preparing is now accepted. It has
not touched the session: it runs the owner check after native selection,
and native selection waits for the save to commit. The earlier
same-boot-only rule was stricter than needed.
- The fence takes share locks on the follow-up's rows whenever it
reaches this check, also when it then refuses. The save transaction is
short. The lock order is the finalization row, then the run row, as in
the claim and defer paths.
- Previous-release state: a claim or park written by a release without
`waitingForOwner` is now accepted, not refused. No stored shape changes.

## Model Used

- Anthropic 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:37:16 -06:00
DottaandClaude Opus 5.5 397f163c7f fix(issues): show tasks held by a resolved no-replay hold as Blocked (#22215)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents can schedule a follow-up check (a monitor) on a task. The task then shows as "Monitoring" until the check is due.
> - A failed run can leave a recovery record that blocks replay of its work. The record can have the status `resolved` and still block, because its evidence keeps `automaticRecovery.replay = "blocked"`.
> - Wake admission treats that record as a hold. It refuses every wake for the task, including the due monitor check, and records the skip with `execution_reconciliation_required`.
> - The task display status counts only `active` and `escalated` recovery records. Thus the task shows "Monitoring" with an overdue check, not "Blocked". The board does not see that a person must act. Agents re-arm the check, and the check stays overdue for days.
> - This pull request makes the display status show these held tasks as "Blocked". It uses the part of the wake-admission hold predicate that is always effective and cheap to query.
> - The benefit is that a task whose wakes are held shows as "Blocked" in the list, in search, in counts and in summaries, and the person who must act can find it.

## Linked Issues or Issue Description

(B) No issue exists. Bug report:

**What happened?**
Scheduled follow-up checks on agent tasks stayed overdue for many days. Each due check was skipped with the reason `execution_reconciliation_required`. One skip record had more than 25,000 merged attempts. The tasks did not show as "Blocked". They showed as "Monitoring" (or as in progress) with an overdue check. Agents re-armed the check, but the check never started.

**What did you expect to happen?**
When wake admission holds a task, the task shows as "Blocked", so a person can see it and use the recovery controls.

**Steps to reproduce**
1. Give an agent an `in_progress` task with a monitor.
2. Add a recovery record for the task with status `resolved`, a reconciliation cause (for example `provider_failure_meaning_unverified`) and evidence `automaticRecovery.replay = "blocked"`.
3. Read the task. `getExecutionBlocker` returns the hold and wake admission refuses the monitor wake.
4. See that `displayStatus` is `monitoring`, not `blocked`.

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

Related open PRs: #14590 and #14156 change how no-replay holds are released. This PR does not change hold release. It only makes the held task visible.

## What Changed

- `server/src/services/issue-display-status.ts`: An agent task with lifecycle status `in_progress` now shows `blocked` when it has a recovery record with these properties:
  - The cause is a reconciliation cause other than `legacy_execution_requires_reconciliation`.
  - The evidence has `automaticRecovery.replay = "blocked"`.
  - The evidence does not have the legacy workspace-restore schema.
  - The task is not a conversation.
- For these records, `executionBlockerPredicate` is always true and `restoreHoldReleasedForCurrentOwnerPredicate` is always false. Thus "Blocked" never shows for a task that wake admission would wake. The exceptions of the full predicate apply only to legacy holds, legacy workspace-restore holds and conversation boundaries. Those keep their current display.
- The full admission predicate is not used in the projection. I tried it first, and list queries became 3 to 4 times slower, because every list, search and count query includes this projection.
- `server/src/__tests__/issue-display-status.test.ts`: New regression test. It also checks that `getExecutionBlocker` agrees with the display status before and after the hold allows replay.

## Verification

- Failing before the fix: `pnpm --dir server exec vitest run src/__tests__/issue-display-status.test.ts`. The new test "shows an overdue monitor behind a resolved no-replay execution hold as Blocked, not Monitoring" failed with `AssertionError: expected 'monitoring' to be 'blocked'`.
- Passing after the fix: the same command. 21 of 21 tests pass.
- Affected suites: `vitest run` on `issue-display-status`, `issue-summaries-routes`, `blocked-inbox-review-wait-scope`, `company-search-service`, `issues-service`, `issue-list-assignee-filter-routes`, `status-cards` and `heartbeat-issue-liveness-escalation`. 8 files, 361 tests pass.
- List cost: a local probe (40 `issueService.list` calls) measured about the same time per call as `master`.
- Typecheck: `pnpm --dir server typecheck` (all layers) passes.
- Not run locally: the full `pnpm verify` selection (2,923 files). CI runs it.

## Risks

- Behavior change: more agent tasks can show as "Blocked". This occurs only when wake admission already refuses their wakes. The task lifecycle status, locks and recovery records do not change. This change does not write data.
- Query cost: the display status adds one small `EXISTS` subquery on `issue_recovery_actions` by company and source task. It runs only for agent tasks that are `in_progress` with no queued or running run and no active recovery record.
- Coverage: tasks held by a resolved legacy reconciliation hold, or by a legacy workspace-restore hold, still show their current status. Their release rules need run-level checks that are too costly for this projection.
- `in_review` and other lifecycle statuses keep their current display.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use (shell, file edit, 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
- [ ] 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:27:05 -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 01d74a52a2 fix(connections): name an expired sign-in in connection search (#22211)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents use connection search to find out if they can use an app, and what a person must do when they cannot
> - When an OAuth provider rejects a refresh token, Paperclip disables the shared connection and records `oauth_reauthorization_required`
> - Connection search then gave only the generic reason "Connection needs attention"
> - Agents could not tell a person the exact action. They had to read large app attention payloads to find the cause
> - This pull request makes connection search name the connection whose sign-in expired and say that a person must reconnect it
> - The benefit is a clear blocker that agents can report in one step, so the connection owner can renew the sign-in sooner

## Linked Issues or Issue Description

**What happened?**
A shared OAuth connection (for example, Sentry) came to the end of its provider grant. Paperclip tried the refresh token. The provider rejected it. Paperclip correctly disabled the connection and set its error to `oauth_reauthorization_required`. After that, `connections_search` returned `state: "needs_user_action"` with the reason "Connection needs attention". Scheduled agent work that needed the app stopped. The agents could not name the cause or the human action from the search result.

**Expected behavior**
Connection search tells the agent that the sign-in for the named connection expired, and that a person who manages the connection must reconnect it.

**Steps to reproduce**
1. Make a shared OAuth tool connection and give an agent access to its tools.
2. Make the provider reject the refresh token (for example, `invalid_grant`). Paperclip sets the connection to draft, disabled, health `error`, and last error `oauth_reauthorization_required`.
3. As the agent, search connections for the app.
4. See the reason "Connection needs attention". It does not say that the sign-in expired.

## What Changed

- `server/src/services/connection-intents.ts`: connection search reads the grants of each matching connection. When a grant in the caller's audience (the organization, the responsible user, or the agent) has status `needs_reauthorization`, and no grant in that audience is active, the reason names that connection. The reason says that the connection must be signed in again, and that a person who manages it must reconnect it on its app page.
- The search uses the same audience rule that protects indexed tool descriptions. A grant of another person does not show the name of that connection.
- The state, `connectionId`, and all access checks do not change.
- `server/src/__tests__/connection-intents-service.test.ts`: add two regression tests. The first test confirms that the healthy connection is `ready`. Then it writes the rows that a rejected refresh writes for an organization grant (grant `needs_reauthorization`, connection `draft` and disabled, no `lastError`), and examines the reason. The second test makes sure that the private connection of another person is not named.

## Verification

- Failing before the fix (in `server/`): `pnpm exec vitest run src/__tests__/connection-intents-service.test.ts -t "must be renewed"`. The shared test failed with `AssertionError: expected 'Review identity and access for this agent' to contain 'Saved sentry'`.
- The private-connection test failed against the first commit of this PR (`lastError` match without an audience check) with `expected 'The sign-in for "Private Sentry of another person" expired. ...' not to contain 'Private Sentry of another person'`.
- Passing after the fix: `connection-intents-service.test.ts` passes (37 of 37).
- Related suites pass: `agent-setup-connection-intents`, `connection-aggregator-fallback`, `satisfied-connection-intents` (168 of 168 with the file above).
- `pnpm run typecheck` in `server/` passes.
- The grant state comes from the refresh writer in `grant-refresh.ts`. Existing tests in `tool-access-service.test.ts` make sure that a rejected refresh sets the grant to `needs_reauthorization`.
- I did not run the full `pnpm verify`.

## Risks

- Low risk. The change only changes the text of one search reason. It does not change state, access decisions, or what agents can call.
- The reason does not use `lastError`, because health checks write display text into that column, and the default refresh path does not write it.
- The member-removal path also sets remaining grants to `needs_reauthorization`. The text "must be signed in again" is correct for that case too.
- I examined the refresh path. Paperclip already tries the refresh token before it marks the grant. This PR does not change that path.
- Out of scope: Paperclip does not send a notification to the connection owner, and the connection request card does not offer to reconnect the existing connection. These need separate changes.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution in an agent harness.

## Checklist

- [x] I have included a thinking path that traces from project context to this change
- [x] I have specified the model used (with version and capability details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] 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:25:00 -06:00
DottaandClaude Opus 5.5 c36e791bd9 fix(native): back off and retry a provider rate limit that reports no reset (#22216)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Native runs drive ACP agents, such as Claude, through the runner. The runner types each provider failure for the server.
> - When a provider limit stops a turn, the server holds the task. It retries the task automatically at the reset that the provider reports (#20692).
> - Claude can reject a request at the account rate limit with "This request would exceed your account's rate limit. Please try again later." This text has no reset time and no window.
> - The server then plans no automatic Retry. The task stays blocked until a person retries it, and the case work stops before a final reply.
> - This pull request gives a `rate_limit` failure without a reported reset the default provider-limit cooldown, and then requests the task's Retry.
> - The benefit is that a short account rate limit no longer strands a task. The existing Retry admission keeps the saved work and all gates.

## Linked Issues or Issue Description

Refs #20692, #19246, #21100

**What happened?**

A native task ran on a Claude agent. In the middle of the turn, Claude returned HTTP 429 with "This request would exceed your account's rate limit. Please try again later." The runner typed the failure as `rate_limit`, with no `retryAt`. The server put the task on hold with "Restore model provider usage capacity, then retry the task. The provider did not report when its usage limit resets." It did not plan an automatic Retry. The task stayed blocked until a person retried it.

**Expected behavior**

A rate limit passes by itself. Paperclip should wait a bounded time, and then retry the task. It should keep the saved work and should not start another request before the wait ends.

**Steps to reproduce**

1. Run a native task on a Claude agent whose account is at its rate limit.
2. Let Claude reject a request in the turn with the 429 account rate-limit text above.
3. See that the task hold has no reset time and that no automatic Retry is planned.

**Paperclip version or commit**

`master` at 8282d386da.

## What Changed

- `readNativeUsageLimitReset` (server, native runtime) now gives a `rate_limit` turn failure without a reported reset an estimated reset. The estimated reset is the failure time plus `PROVIDER_LIMIT_DEFAULT_COOLDOWN_MS` (one hour). This is the same wait that already holds the agent's new work after the same failure, so both holds end at about the same time.
- The reset carries an `estimated` flag. The hold text says that the provider did not report the reset, and it gives the time when Paperclip will retry.
- A `quota_exhausted` failure without a reported reset does not change. It still waits for a person, because an exhausted allowance does not pass by itself.
- The existing bounds still apply: a maximum of three automatic Retries in a row without a successful run, Retry admission gates, and the accountable-user check.
- This change is a fallback. When the runner sets `retryAt` (for example, #21100 for a named rate-limit window) or the text contains a reset, Paperclip uses that time.

## Verification

- New test in `server/src/services/native-runtime/native-provider-capacity.integration.test.ts`: "backs off and retries a Claude account rate limit that reports no reset".
- Before the fix, the test failed: `AssertionError: expected NaN to be greater than or equal to 1795028502736`. The hold had no `providerLimitResetAt`, because no reset was planned.
- After the fix: `cd server && pnpm vitest run src/services/native-runtime/native-provider-capacity.integration.test.ts` passes (11 tests).
- Related files pass: `native-provider-limit-cooldown.integration.test.ts`, `src/__tests__/heartbeat-provider-limit-wait.test.ts`, `task-interruption-presentation.test.ts`, and the capacity file (4 files, 90 tests).
- `cd server && pnpm typecheck` passes.
- `pnpm verify` selected 2,925 of 3,792 Vitest files, because the changed module is deep in the server import graph. Its first selected group passed (2 files, 12 tests). I stopped the broad local run and rely on the required CI test checks for that coverage.

## Risks

- Low risk. The change applies only to a native turn failure that is typed `rate_limit` and has no reported reset.
- If the account stays at its limit for more than one hour, the automatic Retry can fail again. After three automatic Retries in a row, the task waits for a person, as before.
- The task stays in the blocked state during the wait, as it does for a reported reset. A person can select Retry to start it sooner.

## Model Used

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

## Checklist

- [x] I have included a thinking path that traces from project context to this change
- [x] I have specified the model used (with version and capability details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes (no doc change is necessary: no subsystem doc describes this hold, and the hold text and tests describe the behavior)
- [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:24:52 -06:00
DottaandClaude Opus 5.5 f472991647 fix(native-runtime): resolve assigned tool names to the authorized alias (#22213)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work.
> - Native runners give agents their assigned app tools through two wrapper tools: `paperclip_search_assigned_tools` and `paperclip_call_assigned_tool`.
> - Search returns each tool with a hashed alias (`app_<readable>_<digest>`). The description also shows the display name.
> - Agents sometimes pass the gateway tool name or the display name instead of the alias, in `schemaTool` or in the call `name`.
> - The wrapper rejected these values with a bare `assigned_mcp_tool_unknown`. The agent had to search the catalog again before it could call the tool.
> - This pull request resolves an unambiguous name to the authorized alias, and gives a corrective error when the name is not known.
> - The benefit is fewer failed tool calls and fewer repeated catalog searches, with no change to authorization.

## Linked Issues or Issue Description

**What happened?**
An agent searched its assigned tools and then called a tool with the gateway name or the display name (for example `sql_query`). The search with `schemaTool` and the call both failed with `assigned_mcp_tool_unknown`. The call error did not tell the agent what to do.

**Expected behavior**
When the name identifies exactly one tool in the session catalog, the wrapper uses that tool. When the name is not known or is ambiguous, the error tells the agent to use the exact name from search.

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

**Steps to reproduce**
1. Assign an app tool with the display name `sql_query` to an agent on an on-demand native runner.
2. Call `paperclip_search_assigned_tools` with `{"query":"","schemaTool":"sql_query"}`.
3. Call `paperclip_call_assigned_tool` with `{"name":"sql_query","arguments":{...}}`.
4. See `assigned_mcp_tool_unknown` for both calls.

## What Changed

- `server/src/services/native-runtime/assigned-mcp-tools.ts`: add `resolveAssignedName`. It accepts the exact alias. If the value is not an alias, it looks for tools whose gateway name or display name is equal to the value. It resolves only when exactly one tool in the session's pinned catalog matches in either field. It trims surrounding white space.
- Search with `schemaTool` uses the resolved alias. The fresh-grant and work-mode filters still apply to the result.
- `paperclip_call_assigned_tool` uses the resolved alias. An unknown name returns `assigned_mcp_tool_unknown: name must be an exact name returned by paperclip_search_assigned_tools. Search assigned tools again and use the returned name.`
- A name that matches more than one tool returns a different error: `assigned_mcp_tool_unknown: name matches more than one assigned tool. Use the exact name returned by paperclip_search_assigned_tools.` The `schemaTool` path gives the same error, with the text `schemaTool` and `inputSchemaRef`.
- `server/src/services/native-runtime/assigned-mcp-tools.test.ts`: add regression tests.

## Verification

- Failing before the first fix: `pnpm --filter @paperclipai/server exec vitest run src/services/native-runtime/assigned-mcp-tools.test.ts -t "resolves a gateway name"` failed with `promise rejected "Error: assigned_mcp_tool_unknown: schemaTool must match an authorized inputSchemaRef..." instead of resolving`.
- Failing before the review fix (second commit):
  - `rejects a name that is one tool's gateway name and another tool's display name` failed with `promise resolved "{ content: [...] }" instead of rejecting`. The old code ran the read tool `sql_query`, but the write tool has the display name `sql_query`.
  - `resolves a gateway name or unique display name ...` failed with `expected ... 'assigned_mcp_tool_unknown: name matches more than one assigned tool' but got 'assigned_mcp_tool_unknown: name must be an exact name ...'`.
- Passing after the fix: the full file `src/services/native-runtime/assigned-mcp-tools.test.ts` passes (59 of 59 tests).
- The tests also check these safety conditions:
  - An ambiguous display name (two tools named `search`) is rejected, on search and on call.
  - A name that is the gateway name of one tool and the display name of a different tool is rejected, and the gateway receives no call.
  - A write tool that the display name resolves to is still denied in planning mode.
  - A revoked tool is still rejected after the fresh grant list changes.
  - A tool that is not in the pinned catalog is still rejected.
  - The gateway receives only the resolved gateway tool name.
- No other code or test depends on the changed error text (`git grep assigned_mcp_tool_unknown`).
- Not run locally: the full server `tsc --noEmit`. The sandbox did not have enough memory and disk for it. CI runs the typecheck. It passed on the first commit.
- CI on the first commit: `Verify Paperclip Runner (vitest native server)` did not fail a test. All tests that ran passed. The job stopped because the CI runner received a shutdown signal. The cancelled jobs stopped for the same reason.

## Risks

- Low risk. Resolution only maps to tools that are already in the session catalog. The same permission, work-mode, fresh-grant, and gateway checks apply after resolution.
- A name that matches more than one tool, in either field, is not resolved. The agent must use the alias.
- Direct (non-wrapper) tool calls still require the exact alias.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution in an agent harness.

## Checklist

- [x] I have included a thinking path that traces from project context to this change
- [x] I have specified the model used (with version and capability details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [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 15:24:45 -06:00
DottaandClaude Opus 5.5 37de2b7259 fix(tools): keep audit summaries valid jsonb when the cut lands inside an emoji (#22207)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents call connector tools through the tool gateway. The gateway writes an audit row in `tool_call_events` for each call.
> - The audit row keeps short request and result summaries in `jsonb` columns. `summarizeToolValue` cuts long summaries to 3997 UTF-16 code units.
> - When the cut falls between the two halves of an emoji, the summary ends in a lone high surrogate. PostgreSQL `jsonb` rejects this value.
> - The audit insert then fails. The agent gets the database error and not the connector result.
> - This pull request makes the cut keep whole characters.
> - The benefit is that connector calls with long, emoji-rich results return their result and keep their audit record.

## Linked Issues or Issue Description

**What happened?**
Some connector tool calls failed with a database error. The error text starts with `Failed query: insert into "tool_call_events"`. The connector call itself worked, but the agent did not get the result. This occurred in a small part of calls (less than 1%).

**Expected behavior**
The connector call returns its result. Paperclip writes the audit row for the call.

**Steps to reproduce**
1. Call a connector tool that returns a long result (more than 4000 characters) with emoji in it.
2. Make sure an emoji is at the summary cut point (UTF-16 code unit 3997 of the serialized value).
3. The `tool_call_events` insert fails with `22P02 invalid input syntax for type json` ("Unicode low surrogate must follow a high surrogate"). The tool call returns that error.

**Relevant logs or output**
`Failed query: insert into "tool_call_events" (...)` from the gateway `call_completed` audit write. The row has request and result summaries.

## What Changed

- `server/src/services/tool-content-guards.ts`: `summarizeToolValue` now cuts long summaries with a small `cutWholeCharacters` helper. If the last kept code unit is a high surrogate, the helper drops it. The summary is still at most 4000 code units. The `sha256` and `sizeBytes` values do not change, because they use the full serialized value.
- `server/src/__tests__/tool-content-guards.test.ts`: add a regression test. It puts an emoji across the cut point and checks that the summary has no lone surrogate.

## Verification

- Failing before the fix: `pnpm --dir server exec vitest run src/__tests__/tool-content-guards.test.ts -t "without splitting an emoji"` failed. The received summary ended with a lone high surrogate before `...`, and the expected summary did not.
- Passing after the fix: the same command passes. The full file passes (47 tests).
- Database check: on embedded PostgreSQL, the old summary shape as `jsonb` fails with `22P02` ("Unicode low surrogate must follow a high surrogate"). The new summary shape is accepted. I used a temporary probe for this check. I did not commit it.
- `pnpm --dir server typecheck`: no errors in `server`. The local run showed errors only in `cli` and `kv-demo-mcp-server`, because I installed only the server dependencies (low disk space).
- Not run: the full `pnpm verify`. `prompt-injection-prevention.test.ts` does not load in my environment (`baseURL must be a non-empty string`). The same error occurs on unchanged `master`.

## Risks

- Low risk. The change affects only the readable summary text. A summary can be one code unit shorter when the cut point is inside an emoji. Hashes, sizes, redaction, screening, and authorization do not change.

## 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
- [ ] 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:18 -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>
canary/v2026.1118.0-canary.827000
2026-11-18 15:19:11 -06:00
DottaandClaude Opus 5.5 8a295f944d fix(runner): fail fast when an artifact storage read stalls (#22210)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use the `download_artifact` tool to copy a saved API artifact
into their workspace
> - The server reads the artifact bytes from storage before it installs
the file
> - This storage read has no deadline. A stalled storage response or
stream keeps the tool call open
> - The provider MCP client stops the call after about five minutes with
the error "The operation timed out."
> - This pull request puts a 60-second deadline on the storage read and
returns a clear, retryable error
> - The benefit is that the agent gets a fast, clear result and can
retry, and does not wait for five minutes

## Linked Issues or Issue Description

**What happened?**
Some `download_artifact` calls stopped for four to five minutes. Then
the agent got only "The operation timed out." In one case, a retry of
the same 1 MB artifact completed in about 20 seconds.

**Expected behavior**
A stalled storage read must fail quickly. The error must tell the agent
that no file was written and that it can retry the same download.

**Steps to reproduce**
1. Give `PaperclipRunnerToolAuthority` a storage service whose
`getObject` never resolves, or whose stream sends one chunk and then
stops.
2. Call `download_artifact` for an artifact in that storage.
3. The call does not settle. Nothing aborts the storage request.

**Root cause**
`#readApiFile` called `storage.getObject(...)` without a `signal` and
read the stream with no deadline. Other storage reads in the runner, for
example chat attachment reads, already have a deadline.

## What Changed

-
`server/src/services/native-runtime/paperclip-runner-tool-authority.ts`:
the artifact branch of `#readApiFile` now uses a 60-second
`AbortSignal.timeout`. It sends the signal to `storage.getObject`. It
destroys the stream when the deadline expires. Every storage stream gets
an error listener before it can be destroyed, so a late reply cannot
raise an uncaught `AbortError`. It returns HTTP 504 with code
`artifact_storage_timeout` and the message "Artifact storage read did
not finish within 60 seconds. No file was written; retry the same
download."
- A new optional binding field, `storageReadTimeoutMs`, sets the
deadline for tests. The default is 60 seconds. The production callers do
not change.
-
`server/src/services/native-runtime/artifact-transfer.integration.test.ts`:
a new regression test covers a storage response that never arrives and a
stream that stops after one chunk.

## Verification

- Failing before the first fix: `cd server && npx vitest run
src/services/native-runtime/artifact-transfer.integration.test.ts -t
"stalls"` failed with `Error: Test timed out in 15000ms.` The
`download_artifact` call never settled.
- Failing before the late-reply fix: the same test now also covers a
storage reply that arrives after the deadline, with a real
`createReadStream` that gets the aborted signal. It failed with an
uncaught `AbortError` (`ABORT_ERR`).
- Passing after both fixes: the same command passes. Each stalled call
fails in less than 5 seconds with the retryable error. All storage
signals are aborted. No uncaught error occurs. The workspace has no
files.
- `npx vitest run
src/services/native-runtime/artifact-transfer.integration.test.ts
src/services/native-runtime/paperclip-runner-tool-authority.test.ts`: 49
passed.
- `npx vitest run
src/services/native-runtime/runner-api-artifacts.integration.test.ts
src/services/native-runtime/runner-api-artifacts.test.ts
src/services/native-runtime/issue-document-batch.integration.test.ts`:
38 passed (first revision).
- `pnpm run typecheck` (server): passed.
- `pnpm verify` selects a very large set of files for this module. I did
not run the full set locally. CI covers it.

## Risks

- Low risk. The deadline applies only to the artifact read from storage,
and artifacts are at most 10 MiB. A healthy read takes seconds.
- A very slow but working storage provider that needs more than 60
seconds for 10 MiB now gets a retryable error.
- The error occurs before any file write, so no partial file stays in
the workspace.
- This change does not fix a slow storage provider. It makes the failure
fast and clear.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), 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
- [ ] 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:14:46 -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
github-actions[bot]andlockfile-bot fcaf748607 chore(lockfile): refresh pnpm lockfiles (#22220)
## Thinking Path

> - Paperclip uses a dependency lock for reproducible builds.
> - Dependency changes on master need matching lock entries.
> - Paid eval reports also pin a reviewed offline correction.
> - Reports must install before paid model work starts.
> - This automated PR keeps the lock and report proof together.

## Linked Issues or Issue Description

**What happened?**

Dependency manifests on master changed after the last committed lock
refresh.

**Expected behavior**

Frozen installs must match those manifests. Eval reports must retain
matching offline lock proof.

**Steps to reproduce**

Run a frozen install before and after this lock refresh.

## What Changed

- Refresh the dependency lock from the manifests on master.
- Refresh the sandbox provider lockfiles from their manifests on master.
- Include the matching offline report correction and hashes.
- Resync the SDK public source proof's lock pins from the refreshed
lock.

## Verification

- Pinned pnpm resolution completed with lifecycle scripts disabled.
- The report proof refresh accepted the reviewed committed baseline.
- The workflow rejected changes outside the lock and report proof files.

## Risks

The lockfile bot merges this PR without CI or review when every added
package version is at least 3 days old on npm. Otherwise the PR waits
for a maintainer, and the daily refresh tries again. The bot merges only
the exact commit this workflow generated from manifests already reviewed
on master. Unknown report lock baselines remain blocked. This update
changes no permissions or paid enable gates.

## Model Used

None — generated by pnpm and the deterministic report-lock updater.

## Checklist

- [x] Thinking path and problem description included
- [x] Generated lock and matching report proof included
- [x] Release-age gate decides between bot merge and maintainer review

Co-authored-by: lockfile-bot <lockfile-bot@users.noreply.github.com>
2026-11-18 15:01:15 -06:00
DottaandClaude Opus 5.5 7f9c115cc2 fix(github): let a queued push start the next review turn instead of a blocker continuation (#22223)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A GitHub review bot reviews each PR in a task. Each push sends a new
review request to that task as a chat message.
> - A push that arrives during a review waits as a deferred chat wake.
That wake starts a new turn. The turn binds its tools to the newest
pushed commit.
> - #21959 and #22140 continue a run that reports a blocker in a fresh
session. That continuation keeps the source binding of the blocked run.
It also holds the task, so the waiting push request does not run.
> - On staging, a push during a review made the publication fail with
"requested for an older pull request head". The agent reported a
blocker. Paperclip then continued twice with the old binding. Each
continuation finished the review and could not publish it.
> - A second failure mode: a complete re-review that listed only the
files changed since the prior review got a short rejection. The
rejection named no files, and a small model stopped instead of
correcting the submission.
> - This pull request lets a queued chat request take the next turn
instead of a blocker continuation. It also names the missing files in
the coverage rejection.
> - The benefit is that reviews publish for the newest push without a
person, and agents can correct incomplete coverage on the next call.

## Linked Issues or Issue Description

**What happened?**
On staging, automatic GitHub reviews stopped publishing. The bots posted
"Publication is currently blocked" and "Paperclip must authorize the
review for <newest commit>". The run history showed this sequence: a
review run started for the first commit. Two pushes arrived during the
run. Steering into the active run was rejected for both pushes, so they
waited as deferred chat wakes. The run reported a blocker. Paperclip
then started two `native_environment_blocker` continuations. Each
continuation had no message of its own, so its GitHub tools resolved to
the first commit's request and refused the current head. The waiting
push requests did not run until a later push.

**What did you expect?**
A push request that waits behind a run starts the next turn, bound to
that push. The agent then reviews and publishes for the current head.

**Steps to reproduce**
1. Start an automatic review on a PR.
2. Push a new commit while the review runs, so the review request waits
as a deferred chat wake.
3. Let the run report a blocker (for example after the stale-head
publication refusal).
4. See that a fresh-session retry starts with the old binding and the
push request stays deferred.

Refs #21959, #22140, #22066

## What Changed

- `status-arbiter.ts`: new rule before the blocker continuation lanes.
When a blocked run has a queued chat request for the same task and
agent, the decision is `preserve` with only `release_checkout` (reason
`native_blocker_superseded_by_queued_request`). The normal release drain
then starts the queued request. A pause hold or a board-owned blocker
keeps the existing behavior.
- `native-runtime/queued-chat-request.ts`: new `hasQueuedChatRequest`
query. It uses the same chat-wake test that keeps chat wakes out of
first turns (`chatConversationId` or `externalChatProvider`).
- `native-run-finalizer.ts`: supplies `hasQueuedChatRequest` to the
arbiter, only for a blocked report.
- `chat-github-review-policy.ts` / `chat-github-reviews.ts`:
`githubCompleteCoverageGap` replaces the inline check. The rejection now
names the missing files (up to 20), says that a complete review covers
all changed files, and gives the two corrections (add them to
`reviewedPaths`, or submit `complete: false` with `omittedPaths`).

## Verification

- Red/green: `cd server && npx vitest run
src/services/native-runtime/native-environment-blocker.integration.test.ts`.
The new case failed before the fix with reason
`native_environment_blocker` and one scheduled retry, as on staging.
After the fix it passes: no retry, the task stays `in_progress`, and the
chat wake stays deferred for the release drain.
- Red/green: `npx vitest run
src/services/native-runtime/status-arbiter.test.ts -t "queued chat
request"`.
- Red/green: `npx vitest run
src/services/chat-github-review-policy.test.ts -t
githubCompleteCoverageGap`.
- `native-agent-blocker.integration.test.ts` and the full arbiter and
review-policy suites pass.
- `cd server && npx tsc --noEmit -p .` passes.
- `pnpm verify` on the changed files (results in the CI checks below).

## Risks

- Low to medium. The new rule changes only blocked reports that would
otherwise auto-continue while a chat request waits behind the run.
Without a waiting chat request, the behavior does not change.
- The waiting request now starts the next turn instead of the
continuation. If the blocker is real, that turn can report it again, and
the existing lanes apply.
- The finalizer does one more indexed read, only for blocked reports.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code with tool use: code
search, editing, shell, test runs, and staging run inspection through
the 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
- [ ] 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:00:57 -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>
canary/v2026.1118.0-canary.826200
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>
canary/v2026.1118.0-canary.826100
2026-11-18 10:40:31 -08:00
8282d386da docs(release): prepare v2026.1117.0 stable notes before publish (#22094)
<!-- Write all pull request text in Simplified Technical English
(ASD-STE100): short sentences, one instruction per sentence, simple
approved vocabulary, and the active voice. -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Each stable release publishes curated release notes as its GitHub
Release body.
> - The stable release workflow reads
`releases/beta/v2026.1110.0-beta.0.md` from master when it starts. It
publishes that exact revision.
> - The notes on master show v2026.1113.0 and the date 2026-11-13. That
version did not ship.
> - The promotion of `2026.1110.0-beta.0` starts on 2026-11-17, so the
version is `2026.1117.0`.
> - An audit of the release range also found an incorrect contributor
count, user-facing changes that the notes do not cite, and one line that
names Cloud deployments.
> - This pull request corrects all of these before the stable release
starts.
> - The benefit is that the release page shows the correct version,
date, counts and changes.

## Linked Issues or Issue Description

Refs #20610 (the curated notes for the `2026.1110.0-beta.0` soak).

**Problem**
The stable notes for the promotion of `2026.1110.0-beta.0` show `#
Paperclip v2026.1113.0` and `> Released: 2026-11-13`.
`scripts/release.sh stable --print-version --date 2026-11-17` on master
gives `2026.1117.0`. The Contributors line says 37 contributors. The
range has 40. About 70 user-facing PRs in the range are not in the
notes.

**Expected result**
The notes show `# Paperclip v2026.1117.0` and `> Released: 2026-11-17`.
The intro names v2026.1117.0. The counts match the range. The notes
describe the user-facing changes for self-hosted installs.

**Impact**
The stable workflow publishes these notes as the GitHub Release body. If
this pull request does not merge before the release starts, the release
page shows incorrect data.

## What Changed

- Set the H1 to `# Paperclip v2026.1117.0`, the release line to `>
Released: 2026-11-17`, and the version in the intro to v2026.1117.0.
- Set the contributor count to 40. The credited handles do not change.
- Add user-facing fixes that the notes did not cite to the existing
**Fixes** groups: Runs, Messages, Costs, Permissions, Workspaces,
Adapters, Chat and task UI, Connections, and Server and CLI.
- Add seven **Improvements** lines: an experimental Cursor Cloud
provider on the Runner, refreshed model catalogs and CLI pins, AI
account and connector sign-in changes, task page and composer changes,
routine task links, the standalone phone app, and the skill update diff
endpoint.
- Add one line to the Upgrade Guide: first-agent onboarding offers only
Claude and Codex.
- Change the `0437`/`0440` migration sentence so it does not name Cloud
deployments.
- One file changes. No text outside `releases/` changes.

## Verification

- `scripts/release.sh stable --print-version --date 2026-11-17` on
master gives `2026.1117.0`.
- The file has no `1113` or `2026-11-13` strings after the change.
- Audit against `v2026.1106.0..09e24dd12c36251dd12af2d73dbc715ce990f922`
(the `beta/v2026.1110.0-beta.0` source):
  - `git rev-list --count` = 1,586. This matches the notes.
  - All 362 cited PR numbers are in the range.
- Every PR in the range that the notes do not cite was classified as
internal, covered by an existing line, Paperclip Cloud only (kept out),
or user-facing. The user-facing ones are added here.
- `git shortlog -sn` without `github-actions[bot]` gives 40
contributors. This is the same method as the v2026.1106.0 notes. The 31
credited handles are the same.
- The range adds migrations `0375`–`0451` (77 files). This matches the
Upgrade Guide. The new environment variables and their defaults match
the code at the source commit.
- The file on this branch has blob
`dff612e41f915a5a2d9f3e572142e2fee56068a8`.

## Risks

- Low risk. This is a change to documentation only, in one file.
- If the UTC date changes before the release starts, the release
workflow keeps `stable_date=2026-11-17` to match this header.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use (shell,
git, GitHub API) and parallel subagents (Claude Sonnet 5.5) for the PR
classification. Used to compute the version, audit the range, and write
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
- [ ] I have run tests locally and they pass (documentation only; no
tests apply)
- [ ] I have added or updated tests where applicable (not 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>
canary/v2026.1118.0-canary.826000
2026-11-18 09:51:24 -08:00
DottaandClaude Opus 5.5 f0bd99ba8a fix(recovery): wait out a sandbox the provider could not start, with no Retry (#22194)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A task that runs in a sandbox environment first gets a lease from
the environment provider (for example Daytona)
> - Sometimes the provider creates the sandbox but cannot start it.
Daytona then puts the sandbox in its `error` state
> - The Daytona plugin deletes that failed sandbox and rethrows the
provider error. The error has no HTTP status and no errno, so the host
cannot tell that it is a provider-side failure
> - The run fails with `setup_failed`, and the task rests on "Retry when
ready". No agent work had started, and a fresh sandbox works, so a
person must click Retry for something the system can do itself
> - Recovery must just work, and the target for runs that need Retry is
0%
> - This pull request makes the plugin report a removed sandbox that the
provider could not start as structured evidence (the step and the
provider state). The host classifies it as a transient provider failure.
The task then uses the existing bounded retries and the provider-outage
wait from #22139
> - The benefit is that a provider start failure delays the task by
seconds instead of stranding it on Retry

## Linked Issues or Issue Description

Refs #22139 (the provider-outage wait lane that this failure now
reaches). Refs #22128 (setup failure after work; this failure happens
before any work, so that path did not apply).

**What happened?**
In a restart-chaos wave with graceful release swaps on 2026-11-18, two
tasks started a run at 14:51:15Z and 14:51:24Z. Both runs failed at
14:51:53Z with `setup_failed` and `failureCause: lease_acquire_failed`.
The cause was `Sandbox <id> failed to start with status: error, error
reason: null` from the Daytona SDK, for two different sandboxes at the
same moment. Both tasks rested on Retry. A Retry click started each task
again, and both tasks completed.

**Expected behavior**
A sandbox that the provider cannot start is a provider failure before
any agent work. Paperclip deletes it and tries again with a new sandbox,
with no Retry. If the provider keeps failing, the task waits for the
provider without a Retry, and a person gets a working Retry only after
the 30-minute ceiling.

**Steps to reproduce**
1. Make the Daytona create call fail while the new sandbox is in the
provider's `error` state.
2. Assign a task to an agent that uses that environment.
3. The run fails with `setup_failed`, and the task rests on Retry.

## What Changed

- Plugin SDK (`environment-creation-cleanup.ts`,
`environment-acquire-error.ts`, `index.ts`): new
`PluginEnvironmentAcquisitionError`. It carries the acquisition
diagnostic (step, elapsed time, budget, provider state) for a failed
allocation that the provider already removed, with no cleanup envelope.
The acquire RPC error data (`paperclip/environment-acquire-error/v1`)
now carries this diagnostic. `readEnvironmentAcquisitionDiagnostic`
reads it from that envelope. The existing cleanup envelope path is
unchanged. No provider text crosses the RPC.
- Daytona plugin (`plugin.ts`): `destroyFailedCreation` returns the
state of the sandbox that it deleted. When a create fails without an
HTTP status and the deleted sandbox was in the `error` state, the plugin
throws `PluginEnvironmentAcquisitionError` with `providerState:
"error"`. A `build_failed` sandbox (a deterministic snapshot build
failure) and any other state keep the original error.
- Server (`environment-runtime.ts`): the acquire path records the
diagnostic for this run also when the error has no cleanup envelope. A
cleanup envelope for another run, company or environment still records
nothing.
- Server (`environment-provider-unavailable-error.ts`): an acquisition
diagnostic with `providerState: "error"` is the transient reason
`provider_start_failed` ("the provider could not start the sandbox"). It
becomes `EnvironmentProviderUnavailableError`, so the run uses the two
bounded retries and then the provider-outage wait lane (one probe per
environment, 30-minute ceiling).
- `tests/runner-e2e/source-sdk-public-inputs.json`: refreshed pins for
the changed SDK sources (generated by `node
tests/runner-e2e/source-sdk-public-inputs.mjs <sha> --write`).

Module boundaries: the change to the shared SDK contract is additive.
The Daytona plugin owns the provider state. The host reads only the
closed diagnostic fields. A plugin that does not use the new class
behaves as before.

## Verification

- `packages/plugins/sandbox-providers/daytona`: `npx vitest run
src/plugin.test.ts -t "failed sandbox creation cleanup"` (37 passed).
New: "reports a sandbox that failed to start as a removed allocation
with its observed step" (red before the plugin change, green after) and
"keeps the create error when the removed sandbox was build_failed /
started".
- `packages/plugins/sdk`: `npx vitest run
tests/environment-acquire-error.test.ts
tests/environment-creation-cleanup.test.ts` (50 passed). New: the
diagnostic crosses the real worker RPC without provider text, and forged
or unstructured envelopes give no diagnostic.
- `server`: `npx vitest run
src/services/environment-provider-unavailable-error.test.ts
src/__tests__/environment-acquisition-diagnostics.test.ts` (74 passed).
New: the reason is `provider_start_failed` with a transient provider
failure, and a diagnostic that was not recorded for this run is not
retried.
- `server`: `npx vitest run src/__tests__/environment-runtime.test.ts -t
"provider could not start|retains uncertain plugin creation"` (12
passed). New: "records the step of a sandbox the provider could not
start and removed" for a worker error (red before the runtime change,
green after) and for a forged error (not recorded).
- `server`: `npx vitest run
src/services/__tests__/run-failure-diagnostics.test.ts
src/__tests__/heartbeat-process-recovery.test.ts -t
"provider|acquisition|diagnostic"` (167 passed).
- Typecheck: `server` `tsc --noEmit`, `pnpm run typecheck` in
`packages/plugins/sdk` and in the Daytona plugin all pass.
- `pnpm verify` exits 2 (the SDK input registry is a global CI input).
Required CI supplies the broad coverage.

## Risks

- **Automatic retries for a deterministic start failure.** If a provider
image or configuration made every sandbox go to `error`, the task now
waits in the provider-outage lane instead of resting on Retry at once.
The lane uses one probe per environment on a 1, 2, then 5 minute
backoff, and it hands the task to a person with a working Retry after 30
minutes. The aggregate automatic-run brake is unchanged. `build_failed`
is not retried by this change.
- **Shared SDK contract.** The new field is additive. An older host
ignores it, and the run fails as before.
- No database migration. No UI change.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, used in
Claude Code with tool use (shell, file edits) and extended reasoning.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 11:47:33 -06:00
DottaandPaperclip a9dc0df9da fix(ui): clarify dashboard proposal hierarchy (#22180)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - An agent can propose dashboard areas and responsibilities in one
card.
> - The card put the area name above a separate “New area” row.
> - Responsibility rows had no type label and no visible parent
structure.
> - This pull request puts area changes in the heading and nests
responsibility changes below it.
> - People can see what each change creates and where it belongs before
they apply it.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The dashboard proposal card in task conversations and the dashboard edit
module.

**Subsystem affected**

The board UI and its Storybook examples.

**Current behavior**

“New area” appears in a row below the area title. New responsibilities
appear at the same level. Their type is not stated.

**Proposed behavior**

“New area” appears beside the area title. Each new responsibility has a
label and sits below its parent area. Existing areas have a separate
label. Area headings follow the heading level in the dashboard module.

**Reason and benefit**

The person can see the parent area, the change type and the text to
review in that order. Long proposals are easier to scan.

**Breaking changes**

None. Proposal inputs, indexes, dependencies and apply/decline endpoints
stay the same.

## What Changed

- Put area changes and their controls in the area heading.
- Nest responsibility rows under each area. Label additions, rewords,
moves and removals.
- Keep the drop/keep dependency behavior and the existing apply payload.
- Keep area classification and group partitions in one helper. Expose
whether each group has an existing parent area.
- Add Storybook examples for the new hierarchy, a narrow layout and a
mix of new and existing areas.
- Add focused component and browser checks for the hierarchy, responsive
layout and apply payload.

## Verification

- 24 focused unit tests passed across the proposal card, dashboard
module and dashboard helpers.
- 25 Chromium checks passed against current-source Storybook after the
review refactor, with one worker and no retries. They cover six proposal
states in light and dark themes at widths of 390 and 960 pixels, plus
the existing apply payload.
- The UI typecheck passed in low-memory mode after the review refactor.
The initial implementation also passed the static Storybook build;
current-head CI supplies broad build coverage.
- 30 map/catalog tests passed. Catalog checks, token gates and
whitespace checks passed.
- A hierarchy regression failed before the fix and passed after it. A
later hosted-story check found a skipped heading level. The fix passed
the expanded browser checks.
- Initial concurrent browser, build and typecheck runs hit the workspace
memory limit. The final browser pass used one worker and the typecheck
used low-memory mode.
- The first CI build stopped because its runner received a shutdown
signal after the UI build completed. A new CI run checks the review
fixes.
- The local verification selector returned exit 2 because the new
browser spec is a global CI input. [Current-head
CI](https://github.com/paperclipai/paperclip/actions/runs/44333497172)
passed typecheck, build, all selected test suites, E2E shards and the
final verify gate for `e71916cdde90ede313cc167ab8cfb8a5c3bb501a`. No
visual baseline comparison was run because the baseline manifest has no
published snapshots.
- [Greptile reviewed the current
head](https://github.com/paperclipai/paperclip/pull/22180#issuecomment-6982500386)
at 5/5 with no findings. Both earlier maintainability threads are
resolved; two Paperclip reviews remain pending.

## Risks

Low risk. This changes UI structure and labels. Long text and drop/keep
controls must continue to fit at narrow widths. The focused browser
checks cover those states. Storybook uses synthetic API data and does
not prove server persistence or permissions.

## Model Used

OpenAI GPT-6 through Codex, with reasoning, 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
- [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>
canary/v2026.1118.0-canary.825800
2026-11-18 11:29:48 -06: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 a7ea2a799a fix(ephemeral): save retained runtime skill bundles at startup and never strand a volume-free server on lost ones (#22190)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A volume-free server keeps no local volume. It must find every file
it needs in durable storage.
> - Before a volume-free server starts, a data gate refuses to start if
records still point at files on a local disk.
> - Old native runs can keep runtime skill bundles that a release before
#19729 wrote only to its own disk. The gate reports these as
`runtime_skill_assets_require_migration`.
> - On a volume-free server those files are not on the disk, and no
volume can be attached again. So the refusal repeats on every restart,
and nothing can clear it. A staging stack crash-looped like this and
stayed down.
> - This pull request makes the server copy every retained bundle that
is still on its disk into durable storage, and start over the bundles
that are gone, the same way #20990 handles harness backups.
> - The benefit is that a volume-free stack can always start again. No
one has to repair it by hand.

## Linked Issues or Issue Description

Refs #19675, #19729, #20990

**What happened?**

A volume-free staging stack ran for twelve days on a release that kept
runtime skill bundles only on its container disk. When that container
stopped, every newer release crash-looped at boot with `Volume-free
server data is not eligible: runtime_skill_assets_require_migration`.
The old container was gone, so the bundles were gone. The deploy could
not roll back, and a retry could not help.

**Expected behavior**

A volume-free server starts. It saves each retained bundle that is still
on its disk to durable storage. It starts over a bundle that is not on
its disk when the volume-free owner marker proves that no volume is
mounted, and restart recovery owns those runs.

**Steps to reproduce**

1. Retain a native run with an admitted runtime skill bundle that has no
version ID and no durable preservation receipt.
2. Remove the bundle from the instance root.
3. Start the server with `PAPERCLIP_EPHEMERAL_SERVER=true` and the
volume-free owner marker present.
4. Startup fails with `runtime_skill_assets_require_migration`, on every
restart.

## What Changed

- `runtime-skill-preservation.ts`:
- The obligation scan is one generator.
`hasLocalRuntimeSkillObligations` uses it.
- New `preserveLocalRuntimeSkillObligations` copies each obligated run's
bundles with `preserveRuntimeSkillAssets` and returns `{ bundles,
unsaved }`.
- A missing source is decided at its reader:
`readLocalManifest`/`readSource` throw `RuntimeSkillSourceAbsent` (other
instance root, or a missing directory, manifest or listed file). Only
that error marks a run unsaved. Any other failure, including an `ENOENT`
from storage or cache work, propagates.
- `preserveRuntimeSkillAssets` no longer aborts on an invalid or
non-durable existing receipt. It copies the local bytes again and
replaces the receipt.
- One durability helper (`preservedAssetRowDurable` for metadata,
`preservedAssetDurable` with a metadata or object read) replaces the
copies in the scan, staging, locking, preservation and rehydration.
- `runtime-skill-preservation-reference.ts`: the scan matches only null
pins, which is exactly what preservation copies. A non-null pin is a
version pin and cannot become an obligation that nothing can settle.
- `file-manifest-cache.ts`: new `inspectFileManifest` returns
`verified`, `missing` or `changed` from the same walk.
`verifyFileManifest` wraps it.
- `ephemeral-server-contract.ts`: the gate saves the bundles still on
the disk. If none stay unsaved, the blocker clears. Unsaved runs are
waived only when the volume-free owner marker is present, with a
warning. A save failure still refuses. The decision uses the copy pass
result, not another scan. One exported blocker constant.
- `ephemeral-migration-data.ts`: offline enrollment accepts the blocker
and copies the bundles from the attached volume, in a phase after the
package phases. Any unsaved run still fails the enrollment.
- `index.ts`: comment update only.
- Tests: `ephemeral-server-runtime-skill-startup.test.ts` (real scan,
real copy, embedded Postgres) and an S3-gated case in
`ephemeral-migration.test.ts`.

## Verification

- `cd server && npx vitest run
src/__tests__/ephemeral-server-runtime-skill-startup.test.ts`
- Red on `origin/master`: 2 of 3 fail with the production error
`Volume-free server data is not eligible:
runtime_skill_assets_require_migration`.
- Green with this change: all cases pass (lost bundle, saved bundle, no
marker, mixed present and lost, one missing listed file, non-version
pin, mixed pins, non-durable receipt recapture, storage failure, storage
ENOENT, unsaved set).
- `cd server && npx vitest run
src/__tests__/ephemeral-server-startup-run-state.test.ts
src/__tests__/runtime-skill-preservation.test.ts` pass (existing gate
and preservation behavior unchanged).
- `cd server && npx tsc --noEmit -p .` passes.
- `ephemeral-migration.test.ts` needs `PAPERCLIP_TEST_S3_ENDPOINT`. It
typechecks, but it was not run here.

## Risks

- A run whose bundle is lost now starts under restart recovery instead
of blocking the whole server. Recovery of that one run can fail. Before,
the whole server stayed down, and the bundle was lost anyway.
- Startup does more work only when unsaved legacy bundles exist. A
current release saves bundles before admission (#19729), so new runs
never add this work.
- No schema change. No API change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via 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>
canary/v2026.1118.0-canary.825600
2026-11-18 11:00:20 -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
DottaandClaude Opus 5.5 2a43fe3e34 feat(telemetry): add company_id to Cloud direct events from background work (#22183)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud sends server telemetry straight to PostHog
(`server/src/services/posthog-direct/`)
> - Request events get `company_id` from the request context. Background
events have no request.
> - So `agent.task_run`, `routine.run`, `connection.invoked`, and other
background events arrive with `stack_id` but without `company_id`. On
staging, 66 of 66 `agent.task_run` events had a null `company_id`.
> - Without `company_id`, product analytics cannot split agent and
routine activity by company.
> - This pull request lets each background emit site name the company of
the entity that it reports on. Only the direct PostHog transport reads
that company.
> - The benefit is that Cloud background events carry `company_id`, and
the self-hosted collector output does not change.

## Linked Issues or Issue Description

Refs #22006

**Subsystem affected**
Server telemetry: Cloud direct delivery to PostHog
(`server/src/services/posthog-direct/`) and the server emit sites for
background events.

**Problem or motivation**
Cloud direct events from background work have no `company_id`. Heartbeat
runs, scheduled routines, connection invocations, and interaction
updates do not run inside an HTTP request, so the request context gives
no company. On paperclip.staging, all 66 sampled `agent.task_run` events
had `company_id` null.

**Proposed solution**
Add a small AsyncLocalStorage scope, `withTelemetryCompany(companyId,
fn)`, in `server/src/telemetry-company-scope.ts`. Each background emit
site wraps its typed `track*` call with the company id of the row that
it already has. The direct transport reads the scope at track time,
through the existing `captureEventContext()` seam. A live request
company still wins. The collector path never reads the scope.

**Alternatives considered**
1. An optional context argument on the shared `track*` helpers. This
changes the public helpers in `@paperclipai/shared` for a Cloud-only
value, so I did not use it.
2. A scope around each whole work unit (heartbeat run, routine run,
invocation). The emit calls are fire-and-forget and are spread across
many modules, so it is easy to miss one or to leak a company into other
work. A scope at the emit site is narrow and explicit.
3. Let the transport look up the company in the database. The transport
must not query the database.

**Roadmap alignment**
This completes the Cloud direct PostHog work from #22006. It does not
change the telemetry contract.

## What Changed

- Add `server/src/telemetry-company-scope.ts`. It has
`withTelemetryCompany(companyId, fn)` and `scopedTelemetryCompanyId()`.
With no company id, it calls `fn` directly.
- `capturePostHogEventContext()` uses the scoped company when no live
request gives a company. The request company, user, and session behave
as before.
- Wrap these emit sites with the company of their entity:
- `agent.task_run` (`emitAgentTaskRun`, `emitAgentTaskRunById`;
`companyId` is now part of the run that the function reads). This covers
heartbeat, native runtime, recovery, run-dispatch, and watchdog callers.
- `routine.run` (`routineService` dispatch, which covers scheduler,
webhook, and manual runs)
  - `agent.first_heartbeat` (heartbeat agent status)
  - `connection.created`, `connection.updated`, `connection.invoked`
  - `interaction.created`, `interaction.resolved`
- `agent.task_completed` (issue route; the issue company is the fallback
when the request gives no company)
- Request-only events (`project.created`, `goal.created`,
`agent.created`, `routine.created`, `skill.imported`) keep the request
context. `server.started` and `error_handler.crash` are not
company-scoped. Dynamic plugin and `question_response.delivery` events
are not in the contract, so the direct path drops them.
- Update the "Cloud Direct Delivery" section of
`packages/shared/src/telemetry/README.md`.

Design note on module boundaries: the scope lives beside
`server/src/telemetry.ts`, not inside `posthog-direct/`. Emit sites do
not import the transport, and the transport does not know which services
exist. The shared telemetry package does not change.

## Verification

- Red/green: with the source changes removed, these 4 new tests fail.
With the changes, they pass.
- `agent-task-run-telemetry.test.ts`: `emitAgentTaskRun` and
`emitAgentTaskRunById` track in the run company scope.
- `routine-run-telemetry.test.ts`: a routine run tracks in the routine
company scope.
- `posthog-direct-telemetry.test.ts`: on Cloud, background
`agent.task_run` and `routine.run` (also after an `await`) carry
`company_id`, and an unscoped event does not.
- `posthog-direct-telemetry.test.ts`: a live request company wins over
the scope, and the scope fills the gap when the request has no company.
- Red/green per emit family: the tests for `connection.created`,
`connection.updated`, `connection.invoked`, `interaction.created`,
`interaction.resolved`, `agent.first_heartbeat`, and
`agent.task_completed` assert the company scope at track time. With the
emit-site wrappers removed, all 7 assertions fail.
- New guard test: on self-hosted, a scoped `agent.task_run` and
`routine.run` produce a byte-identical collector envelope with no
`company` text.
- `cd server && npx vitest run` on 16 telemetry, PostHog, routine,
heartbeat status, interaction, and connector test files: 408 passed.
- `pnpm --filter @paperclipai/server typecheck`: passed.
- Local check with a real `posthog-node` client sent to a local capture
server (never real PostHog), embedded Postgres, and a real
`routineService.tickScheduledTriggers()` tick plus `emitAgentTaskRun`:
- Cloud mode: the captured `routine.run` (`source: schedule`) and
`agent.task_run` both had the seeded `company_id`, plus `stack_id` and
`environment`. `server.started` had no `company_id`.
- Self-hosted mode: the collector body from this branch and from
`origin/master` are identical after I normalize random ids and
timestamps.
- I did not boot a full Cloud-managed server, because it needs S3 and an
external Postgres. The check above uses the same server modules and the
real PostHog client.

## Risks

- Privacy review: this is a Telemetry change under
`rules/data-paths.mdc`, so I request a privacy review. Background Cloud
events now send the real Paperclip `company_id` to PostHog. #22006
already approved `company_id` as a Cloud direct property for request
events. This PR only fills it for background events. It adds no new
property, dimension, or event, so the generated contract does not
change. `packages/shared/src/telemetry/README.md` is updated in this PR.
- Low runtime risk. The self-hosted collector path does not read the
scope, and a test proves its output does not change.
- On Cloud, more events now have `company_id`. No event loses a field.
- If a request with a company tracks an event for an entity in a
different company, the request company wins. This is the same as before
this change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, and test runs).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1118.0-canary.825300
2026-11-18 10:34:39 -06:00