mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
a4c570aede7b6cb36eecc0c7163f67ee90283f60
13
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
e40a16e5c5 |
fix(heartbeat): let Stop take a task out of the agent's queue (#21407)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Each agent runs a limited number of tasks at once. Other tasks wait
in line as queued runs.
> - An agent can have hundreds of waiting tasks. People need one click
to take a task out of line.
> - Stop already cancelled a queued run, but a task that was in progress
stayed in progress. It still looked busy.
> - The classic task thread also hid Stop until the run started.
> - This pull request makes Stop on a waiting task free the task and
show it as not started, in both thread views.
> - The benefit is that people can clear a long queue one task at a
time, and the agent moves on to its next task.
## Linked Issues or Issue Description
**What happened?**
An agent had many queued runs. A person pressed Stop on a task that
waited in line. The run was cancelled, but the task stayed "in
progress". In the classic thread, Stop did not show until the run
started.
**Expected behavior**
One Stop click takes the task out of line. The queued run and its wake
are cancelled. The task lock is released. The task does not look in
progress. No new run starts for that task. The agent's next waiting task
still starts. An activity entry records the change.
**Steps to reproduce**
1. Give an agent one run slot and keep it busy.
2. Assign two more in-progress tasks to the agent, so their runs wait in
line.
3. Press Stop on one waiting task.
4. See that the task still shows "in progress".
**Paperclip version or commit**
`master` at
|
||
|
|
2483cb46c2 |
feat(plugins): deliver configured environment to plugin Runner tasks (#21280)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - An agent gets environment variables from its execution environment, its own configuration, its project, and its routine. Secrets are resolved for each run. > - A plugin environment can run the agent as a native Runner task on its own host, through the environment task contract. > - That contract has no field for the agent's variables. Runs on a plugin environment get only the variables that the plugin sets itself. > - This pull request adds a versioned contract field for the values, sends them on a session handoff, lets Codex commands inherit the variables in an external sandbox, and lets a plugin protect the variables that it sets itself. > - The benefit is that plain and secret variables work on plugin environments in the same way as on local environments. ## Linked Issues or Issue Description Refs #21233. That pull request by @lucktastic finds the same gap and proposes the same capability and field names (`configuredEnvironmentVersion: 1`, `configuredEnvironment`). This pull request uses the same names, so providers implement one contract. It differs in these places: - Codex commands get the variables through an external-sandbox denylist, not through key names sent at `prepare`. A retained Runner does not need a new preparation when a key is added or removed. - A session handoff `resume` gets the values, because it starts a new Runner on another computer. Value changes on the same computer need no new field: Core's process reuse key includes the values, so Core starts a new task. - A driver can declare `protectedEnvironmentKeys`. Paperclip rejects or warns when one is saved. - The run log names skipped variables only for an older provider. Thank you to @lucktastic for the diagnosis and the contract shape. **What happened?** An agent has environment variables, plain and secret. Its runs on a plugin task environment do not get them. `PAPERCLIP_CONFIGURED_ENV_KEYS` in the run lists only the variables that the plugin sets. **Expected behavior** Each run gets the agent's configured variables. **Steps to reproduce** 1. Set a plain and a secret environment variable on an agent. 2. Assign the agent to a plugin environment that provides Runner tasks. 3. Start a run. Read the names in `PAPERCLIP_CONFIGURED_ENV_KEYS` in a command that the agent runs. 4. The agent's names are not in the list. ## What Changed - **SDK contract** (`packages/plugins/sdk/src/environment-tasks.ts`): - A provider advertises `configuredEnvironmentVersion: 1` on `describe`. - `submit` gets `configuredEnvironment`. `resume` gets it only for a session handoff. - Names, count, and sizes have the same limits as the Runner projection. - **Server**: - `createRunnerdBackendWithinSessionClaim` gives the run's configured projection to the plugin task owner. The projection has no provider credentials and no generated runtime keys. - `createPluginRunnerTaskOwner` sends the fields only to a provider with the capability. An older provider gets no new field, and the run log names the variables that were not set. The log never prints values. - **Codex** (`codex-security-config.ts`): - An externally sandboxed launch uses `inherit="all"`, `ignore_default_excludes=true`, and an `exclude` list of Codex's own credentials, instead of an `include_only` list fixed at preparation time. - A test reads the Runner's Codex environment keys, and fails if a new key is not classified. - Host launches keep the bounded allowlist. - **runnerd** (`codex_provider.rs`): `runtime_notification_codex_args` still grants the notification files to read-only profiles when no allowlist is present. Plan mode in an external sandbox needs these grants. - **Protected keys**: - An environment driver can declare `protectedEnvironmentKeys` in its manifest. - Paperclip rejects a protected key on an agent or environment that uses the driver. The 422 has code `protected_environment_variable`. - On a project, a routine, or another agent, Paperclip saves the key. The response has a `configurationWarnings` notice that names the environments. The project and routine pages show the notice as a toast. The agent pages already show configuration warnings. - **Docs**: `doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md` describes the provider obligations. - `tests/runner-e2e/source-sdk-public-inputs.json`: refresh the reviewed SDK source pin. ## Verification - `packages/plugins/sdk`: `vitest run tests/environment-tasks.test.ts` (38 pass). Accepts bounded values. Rejects bad names, NUL bytes, too many variables, and oversized values. - `server`: `vitest run src/services/native-runtime/plugin-runner-task.test.ts` (95 pass). Values go only to a provider with the capability, never in `prepare`. `resume` sends values only for a handoff. - `server`: `vitest run src/services/protected-environment-keys.test.ts src/__tests__/project-routes-env.test.ts` (10 pass). Rejection, notices, and the project route response. - `server`: all route suites that import the project, routine, environment, or agent routes (45 files, 1689 pass). - `packages/shared`: `vitest run src/validators/plugin.test.ts` (64 pass). - `packages/paperclip-runner`: `vitest run src/drivers/codex src/configured-environment.test.ts src/live/runner-provider-launch.test.ts` (444 pass). - `packages/paperclip-runner/runner`: `cargo test -p paperclip-runner-core --lib runtime_notification` (9 pass, 2 ignored as before). - `pnpm typecheck` in `packages/shared`, `packages/plugins/sdk`, `packages/paperclip-runner`, `server`, and `ui`. - Not run locally: `pnpm verify --full` and browser suites. Required CI covers the final revision. ## Risks - **Existing providers:** low risk. Core sends no new field to a provider without the capability. Their runs behave as before, with one added log line when variables were skipped. - **Codex in an external sandbox:** commands now see every variable in the Runner environment except Codex's own credentials. The execution environment builds that environment from an allowlist. If the Runner gives Codex a new credential, the drift test fails until the key is classified. - **Saving env:** new rejections happen only when an installed driver declares `protectedEnvironmentKeys`. No driver declares them today. - **Providers:** they must keep the values transient and never save or log them. The doc lists these obligations. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [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> |
||
|
|
0f3a6a867d |
fix(recovery): continue open agent tasks left with nothing running, pending or waiting on a person (#21139)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents work on tasks through runs, and recovery code starts the next run when a run stops > - On staging, many open agent tasks show "running" or "blocked", but no run, wake or retry is pending, and no person has to act > - Staging deploys about every 40 minutes. Each deploy stops some runs, and some tasks then stay idle until a person presses Retry > - The stranded sweep has many lanes. Some lanes get "no retry" back and skip the task with no record, and the sweep never looks at `blocked` tasks > - This pull request adds one invariant with one pure predicate, and one event-driven sweep that repairs a violation with one ordinary continuation wake > - The benefit is that no open agent task stays with nothing running, nothing pending and no one else's move ## Linked Issues or Issue Description Refs #21107 and #21046 (the pattern for leaving a run of another live server alone). Related open work: #21135 (fresh continuation from saved work at wake admission), #21124 (sweep calls the bounded scheduler for pre-provider legacy failures), #21127 (run-start hand-over). **What happened?** On a staging snapshot (2026-11-12, about 14:35Z), 1,030 open agent tasks had no live run. The new predicate, run read-only against the staging API, classifies 141 of them as violations: 40 offer a Retry only the system can act on, 38 are blocked with no recorded reason and no hold, 14 are blocked by an automatic recovery outcome with no hold left, 5 have nothing pending, and 44 are blocked under an active recovery hold (left to the hold's owner, see below). 25 more are blocked by recovery for more than 7 days. The other tasks wait on a person or on a pending intent: 542 chat threads, 122 agent-declared blocks, 102 credential waits, 51 dependencies, 28 questions. Nine Retry-started `in_progress` tasks show the main gap. A person pressed Retry, a deploy stopped the run during setup (`server_shutdown_interrupted`, no provider work), and the bounded scheduler then refused with `continuation_user_authorization_missing` ("could not revalidate the original user continuation") on every sweep. The sweep's escalation did not take effect either, so each task stayed `in_progress` with a Retry button and nothing pending, for up to 10 hours. **Expected behavior** Each open task assigned to an agent has a live run, a durable pending intent, or a named reason that is someone else's move. If it has none of these, Paperclip continues the task automatically. **Steps to reproduce** 1. Start a person's Retry on an `in_progress` task with a legacy agent. Stop the server during setup, so the run ends `interrupted` with `server_shutdown_interrupted`. 2. Let the bounded retry scheduler refuse to revalidate the person's continuation. 3. Run the stranded sweep. Nothing is queued. The task stays `in_progress` with nothing pending. 4. The same happens for a native predecessor (`enqueueStrandedIssueRecovery` returns `null` for every native run) and for every `blocked` task (the sweep reads only `todo`, `in_progress` and `in_review`). ## What Changed - `server/src/services/recovery/assigned-work-invariant.ts`: the invariant as one pure predicate. Facts go in. The verdict is `ok` with its clause (live run, pending intent, or one reason from a closed list of waits), `settling` with a re-check time, or `violation` with its reason. An unknown hold, block reason or person action is a violation. It also holds the per-task continuation allowance: at most 6 per hour (the server-restart lane's bound, the same cap as #21135) and, below the cap, a spacing of 2, 4, 8 and then at most 15 minutes. At the cap the next try waits until the oldest continuation leaves the hour, so a task that keeps needing continuation is retried at about 6 per hour, never left for hours. - `server/src/services/recovery/assigned-work-sweep.ts`: an indexed pre-filter, a batched fact loader, the repair and a read-only report. - A running run counts as live unless the shared owner proof (`owner-proof.ts`) proves its server gone. A held controller lease is live, so a run of the other server in a deploy overlap is never touched. A run whose owner is proven gone goes to heartbeat's existing lost-process settle path. Native running runs are always treated as live; the native settle watch judges their owners. - Native active paths match the stranded sweep's check, including #21108's exclusion of a native finalization that a person's Retry replaced. - A run that ended less than 90 seconds ago, or whose controller lease another server still holds, is `settling`. The sweep looks again at that deadline. - A pending question counts as the person's move, unless the person pressed Retry (or sent a message) after the question was asked. - The repair takes the task's row lock, checks again that nothing is pending, applies the allowance and writes a plain-language activity entry. This entry is the claim, so two servers make one wake. For a `blocked` task with no recovery hold, it also puts the task back to the status the block recorded. Then it enqueues one ordinary `issue_continuation_needed` wake. The wake has no retry link, so it does not use the task's failure allowance. With #21135, wake admission turns that wake into a fresh run from saved work when a hold would defer it. - A `blocked` task under an active recovery hold is reported as a violation but not repaired here: the hold's owner (#21135) re-continues it, so the two never continue one task twice. When #21124 escalates once on a permanent scheduler refusal, the task is blocked under a hold, so #21135 continues it; when no hold is left, this sweep continues it. Neither case leaves the task waiting on a person for a reason that is not the person's. - The claim re-runs the full predicate on a fresh read under the task's row lock, so a question, approval, blocker, monitor, wake or run that appeared after the first read stops the repair. - A lifted block is restored to the status the blocking entry recorded (`_previous.status`, `previousStatus` or `fromStatus`). A block that interrupted a review goes back to `in_review` with no agent wake; the review's own recovery wakes its participant. If admission refuses the wake, the block is put back with its original block time. - The settling window is keyed on three events only: the latest run ending (a held lease can extend it, but never past 5 minutes after the run ended), a never-run task's creation, and a blocker finishing. Routine touches (comments, reads, labels) never postpone a repair. A run cut by a deploy's shutdown is repaired about 90 seconds after it ended. - Each process starts at most 10 repairs per minute, newest-updated tasks first. The other tasks wait for a deadline. - Each burst of checks writes one structured log line (`assigned_work_invariant.pass`) with the counts by clause, the repairs and the deferrals. - `server/src/services/recovery/work.ts`, `issue-recovery-notifications.ts`, `delivery-work-notifications.ts`: a new `assigned-work-invariant` queue on the shared delivery-work coordinator. The existing issue-recovery notifications (run state changes, hold resolutions) and server start mark a company dirty. There is no interval polling. Deadlines exist only for a real obligation (settling grace, back-off, rate-limit deferral). - `server/src/services/recovery/service.ts`, `heartbeat.ts`: wire the sweep with the existing wake, live-execution and settle dependencies. - `server/src/routes/agents.ts`, `server/src/routes/openapi.ts`, `docs/api/agents.md`: `GET /api/companies/:companyId/assigned-work-invariant` (board only, company-scoped) and filtered by the caller's issue-privacy condition: private tasks the caller cannot read are absent from every count and sample returns the counts by clause, the violation count, the held subset, stale blocks and up to 20 samples. Use it after a deploy to check for 0 violations. Why there are two sweeps: the stranded sweep decides how a known failure resumes (bounded retries, disposition repair, review recovery, escalation). The invariant decides only that something is pending, and repairs with the ordinary continuation. It does not change the stranded sweep's lanes or the recovery-refusal paths. ## Verification - `server/src/services/recovery/assigned-work-invariant.test.ts` (45 tests): every clause, every wait reason, the unknown cases, settling, the allowance and its long back-off. - `server/src/__tests__/assigned-work-invariant.test.ts` (17 tests, embedded Postgres): a refused or later-declined continuation stays a violation and is retried under the cap; the real wake queue deferring behind a recovery hold; scheduling stops when a task is done, cancelled or reassigned to a person; running vs stopped or blocked session goals; the deploy-interrupted Retry shape and the native reconciliation shape (the stranded sweep does nothing, then exactly one wake); the nine Retry-started tasks whose scheduler refused revalidation, including one with a question asked before the Retry; a block after a legacy run's retries ran out with no hold left (`controller_lease_lost`); a block under an active hold left to its owner; two concurrent sweeps make one wake; another live server's run is not touched; an owner-gone run is settled; approval, question, dependency and declared-unblock tasks are not touched; an unknown block reason is repaired; the per-task cap and the per-process budget; a run that ended seconds ago; old-shaped rows (a board-owned stranded action from an older release, native `awaiting_runner_reattach` and `retryable_failure`, a running run saved without its controller process, a block older than 7 days); query cost at staging size. - Query cost at staging size (800 open tasks, 14,000 runs over 7 days): one suspect page 2 ms, one task check 165 ms (including the repair), a full 800-task report 386 ms. The suspect anti-join uses the run status index (no sequential scan on `heartbeat_runs`, 0.2 ms). - Route test in `agent-live-run-routes.test.ts`: a board operator reads its own company; another company and an agent get 403. - Existing production-wiring suites pass with the new queue: `issue-recovery-deadlines`, `issue-recovery-conversations`, `live-recovery-work`, `issue-recovery-work-lifecycle`, `recovery-deadline-acceptance`, `server-startup-feedback-export`, `heartbeat-held-comment-wake`, `delivery-work-coordinator`. - `node scripts/typecheck-layers.mjs` for the server source layers passes. ## Risks - On the first deploy, the sweep continues about 97 staging tasks over about 10 minutes (10 per minute). Each continuation is an ordinary run. - The stranded sweep can still move a task to `blocked` after its bounded retries. The task is then continued by the hold's owner or by this sweep, within the same cap and back-off. The task gets more activity entries than before. - On current master without #21135: when the wake reaches a task whose last run left a recovery hold, admission defers it (a skipped wake, no pending row). The activity entry then says the continuation did not start, the task stays a violation, and the sweep tries again with spacing (2, 4, 8, then 15 minutes at most; at most 6 per hour). It never loops faster than the cap and never moves the task to blocked for a person. A test with the real wake queue covers this. With #21135, the same wake becomes a fresh run from saved work. - The activity entry is written as an attempt and is published only after admission: as queued, or as not started. A wake that the queue declines later (for example behind the old run's cleanup) leaves the task a violation, and it is retried under the cap. - Chat-thread tasks are left out (the conversation clause), because their next move is a person's message. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, test runs, read-only staging API reads). ## 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> |
||
|
|
9dfdeaad86 |
Refine agent workspaces and organization charts (#20973)
Refine agent details, identity editing, responsive controls, and organization charts with three card tiers, clearer save feedback, and stable filtering. Guard instruction-file renames and root configuration updates in one transaction through the agent lifecycle integration, preserving conflict checks, rollback, and configuration history. Co-Authored-By: Paperclip <noreply@paperclip.ing> |
||
|
|
0d4b1d8c89 | Gate agent plugin tabs by execution environment (#20657) | ||
|
|
d53fa727e1 |
docs: use a supported agent role in role examples (#16449)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Every agent has a role, and the API only accepts the values in `AGENT_ROLES` (`z.enum(AGENT_ROLES)` in `packages/shared/src/validators/agent.ts`) > - The board-operator guide, the API docs and the agent-facing API reference are where operators and agents learn which role values to send > - They name `manager` as a role, but `manager` is not in `AGENT_ROLES`, so creating an agent with it is rejected with `invalid_value` > - This pull request replaces the unsupported value with supported ones in the guide and in the two places that show the same invalid value in an example > - The benefit is that the documented role values match what the API accepts ## Linked Issues or Issue Description - Fixes: #15687 ## What Changed - `docs/guides/board-operator/managing-agents.md`: the Role list now reads `ceo`, `cto`, `pm`, `engineer`, `researcher`, etc. (`pm` replaces the unsupported `manager`). The next bullet already says Reports to is the agent's manager in the org tree, so the hierarchy is still described and no extra wording was added. - `docs/api/agents.md` and `skills/paperclip/references/api-reference.md` (two examples): the same invalid value appeared as `"role": "manager"` in response examples for an "EngineeringLead" / "VP Engineering" agent. Changed to `cto`, which is a supported role and fits those examples. These are single-word changes made so the documented examples do not contradict the guide. - Left alone on purpose: ordinary uses of the word "manager" in prose (reports-to wording, AWS Secrets Manager), the "Worked Example: Manager Heartbeat" heading, the planning docs under `doc/plans/`, and a code test fixture (`ui/src/components/RoutineOverview.test.tsx`). - No code, validation or enum change; no new role. ## Verification - Before: the guide lists `manager`, and `AGENT_ROLES` (`packages/shared/src/constants.ts`) is `ceo, cto, cmo, cfo, security, engineer, designer, pm, qa, devops, researcher, general`, with no `manager`; the create validator uses `z.enum(AGENT_ROLES)`. - After: every role value named in the changed lines (`ceo`, `cto`, `pm`, `engineer`, `researcher`) is in `AGENT_ROLES`. `git diff --check` is clean. `pnpm-lock.yaml` is unchanged. - This is a docs-only change (3 files, 4 lines), so I did not run the test suite and did not add a test; there is no docs lint script that runs without installing dependencies. - To check by hand: send `POST /api/companies/{companyId}/agents` with `"role": "manager"` (rejected with `invalid_value`) and with `"role": "pm"` (passes role validation). ## Risks - Low. Documentation only, no runtime behavior change. - `cto` in the two example responses is a judgment call for the "EngineeringLead" / "VP Engineering" sample; any supported role would also be valid there. The two extra files are example-only and can be dropped if a maintainer prefers this PR to touch only the guide. > 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 - Implementation: Anthropic Claude Sonnet 5.5 (`claude-sonnet-5-5`), medium reasoning effort, with tool use and code execution through Claude Code. Context window not reported by the runtime. - Coordination and this description: Anthropic Claude Sonnet 5.5 (`claude-sonnet-5-5`). - Independent review of the exact head: OpenAI Codex `gpt-5.6-sol`, medium reasoning effort, read-only, no findings. - The issue was picked by an automated screening agent; a human contributor directed the work and owns 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 - [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 Sonnet 5.5 <noreply@anthropic.com> |
||
|
|
2d1b531a49 |
[codex] Add clear-error agent action (#7695)
## Thinking Path > - Paperclip is the open source control plane people use to manage AI agents for work. > - Agent runtime state is surfaced in both the server API and the board UI so operators can tell whether an agent is idle, running, paused, or in error. > - When an agent is already in `error`, the existing pause/resume action slot is not useful because there is no running work to pause. > - Operators need a direct, audited recovery path that clears the stale error state only for agents in the same company. > - This pull request adds a company-scoped clear-error mutation, exposes the shared API contract, and wires the board action cluster to show Clear error in the pause/resume slot for errored agents. > - The benefit is that operators can recover CEO/CTO-style errored agents without resorting to database edits or unrelated session reset actions. ## Linked Issues or Issue Description Refs #4021 Paperclip issue: PAP-10515 — right now the CEO and CTO agents are in error state, but there is no way to clear the error; they appear otherwise fine. ## What Changed - Added shared constants, API path, and agent status type support for a company-scoped clear-error action. - Added the server service and route to clear an agent from `error` back to `idle`, with company access enforcement and activity logging. - Added OpenAPI/docs coverage for the clear-error endpoint. - Added backend coverage for service behavior and cross-tenant authorization. - Updated the board agent action cluster to show a red-tinted Clear error button only when `agent.status === "error"`. - Updated agent properties to show a red active last-error indicator only while the agent is currently errored. - Added UI component tests for the error-state action and the non-error pause/resume behavior. ## Verification Local: - `pnpm exec vitest run server/src/__tests__/agents-service-clear-error.test.ts server/src/__tests__/agent-cross-tenant-authz-routes.test.ts ui/src/components/AgentActionButtons.test.tsx` - `pnpm --filter @paperclipai/ui typecheck` - `pnpm exec vitest run server/src/__tests__/openapi-routes.test.ts` PR checks: - Main Paperclip workflow is green on `a7378e584d50594e7bd507a1a02985bfaaa5abf8`. - Greptile is 5/5 with no files requiring special attention and no new comments on the latest review. - `commitperclip PR Review` is still red because its security-gate step canceled after filing a draft advisory; the linked `security-review` check is neutral and says the draft advisory is not a merge block. Visual artifact: -  ## Risks Low to medium risk. The mutation is intentionally narrow, but reviewers should check that clearing `lastError`/`lastRunError` and returning to `idle` is the desired recovery semantics for every adapter state. The remaining red check is from the external commitperclip security-review workflow, not from the code/test workflow for this PR. > 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 OpenAI Codex, GPT-5-family coding model, tool-assisted with local shell, git, GitHub CLI, and targeted Vitest 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [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 |
||
|
|
7f893ac4ec |
[codex] Harden execution reliability and heartbeat tooling (#3679)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Reliable execution depends on heartbeat routing, issue lifecycle semantics, telemetry, and a fast enough local verification loop to keep regressions visible > - The remaining commits on this branch were mostly server/runtime correctness fixes plus test and documentation follow-ups in that area > - Those changes are logically separate from the UI-focused issue-detail and workspace/navigation branches even when they touch overlapping issue APIs > - This pull request groups the execution reliability, heartbeat, telemetry, and tooling changes into one standalone branch > - The benefit is a focused review of the control-plane correctness work, including the follow-up fix that restored the implicit comment-reopen helpers after branch splitting ## What Changed - Hardened issue/heartbeat execution behavior, including self-review stage skipping, deferred mention wakes during active execution, stranded execution recovery, active-run scoping, assignee resolution, and blocked-to-todo wake resumption - Reduced noisy polling/logging overhead by trimming issue run payloads, compacting persisted run logs, silencing high-volume request logs, and capping heartbeat-run queries in dashboard/inbox surfaces - Expanded telemetry and status semantics with adapter/model fields on task completion plus clearer status guidance in docs/onboarding material - Updated test infrastructure and verification defaults with faster route-test module isolation, cheaper default `pnpm test`, e2e isolation from local state, and repo verification follow-ups - Included docs/release housekeeping from the branch and added a small follow-up commit restoring the implicit comment-reopen helpers that were dropped during branch reconstruction ## Verification - `pnpm vitest run server/src/__tests__/issue-comment-reopen-routes.test.ts server/src/__tests__/issue-telemetry-routes.test.ts` - `pnpm vitest run server/src/__tests__/http-log-policy.test.ts server/src/__tests__/heartbeat-run-log.test.ts server/src/__tests__/health.test.ts` - `server/src/__tests__/activity-service.test.ts`, `server/src/__tests__/heartbeat-comment-wake-batching.test.ts`, and `server/src/__tests__/heartbeat-process-recovery.test.ts` were attempted on this host but the embedded Postgres harness reported init-script/data-dir problems and skipped or failed to start, so they are noted as environment-limited ## Risks - Medium: this branch changes core issue/heartbeat routing and reopen/wakeup behavior, so regressions would affect agent execution flow rather than isolated UI polish - Because it also updates verification infrastructure, reviewers should pay attention to whether the new tests are asserting the right failure modes and not just reshaping harness behavior ## Model Used - OpenAI Codex coding agent (GPT-5-class runtime in Codex CLI; exact deployed model ID is not exposed in this environment), reasoning enabled, tool use and local code execution enabled ## 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) - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
|
6a101e0da1 | Add OpenCode provider integration and strict model selection | ||
|
|
09d2ef1a37 |
fix: restore docs deleted in v0.2.3 release, add Paperclip branding
- Restored docs/ directory that was accidentally deleted by `git add -A` in the v0.2.3 release script - Replaced generic "P" favicon with actual paperclip icon using brand primary color (#2563EB) - Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark) - Updated docs.json with logo configuration for dark/light mode - Fixed release.sh to stage only release-related files instead of `git add -A` to prevent sweeping unrelated changes into release commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
||
|
|
28bf5e9e9b | chore: release v0.2.3 | ||
|
|
cabd16bc70 | docs: sync docs and skills updates from backup branch | ||
|
|
02dc46e782 |
docs: add external documentation site content
Add structured documentation covering quickstart, architecture, core concepts, API reference, adapter guides, CLI commands, deployment options, and operator/developer guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |