0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-29 04:25:52 +01:00

Files

T

DottaandPaperclip b508a05c43 feat: add internal agent complaints and suggestions (#15367 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents use legacy skills or native runner tools to work on tasks.
> - Those agents can encounter friction that does not belong in the task
thread.
> - A complaint should preserve the raw reaction. A suggestion should
describe an improvement.
> - This pull request adds attributed local storage and both submission
paths.
> - Agents can submit feedback once and continue their primary work.

## Linked Issues or Issue Description

**Subsystem affected**

Server, database, shared contracts, runtime skills, and native runner
tools.

**Problem or motivation**

Agents have no default internal channel for incidental complaints and
suggestions. Sending this feedback through task comments adds noise and
can alter task workflows.

**Proposed solution**

Store free-form feedback in the current instance database. Derive agent,
run, company, and task attribution from active authority. Provide
default legacy skills and provider-neutral native actions. Keep the
instructions close to Warp's MIT-licensed originals.

**Alternatives considered**

Task comments and external Slack delivery add unwanted side effects.
Mandatory suggestion fields and short editorial limits would discard
useful feedback. This release has no listing API, UI, read tool,
automatic triage, or external forwarding.

**Roadmap alignment**

This is a maintainer-requested addition to the existing runtime skills
and runner tool paths. It does not duplicate a listed roadmap milestone.
Searches for complaint tooling, suggestion-box, and agent commentary
found no overlapping public PR or issue.

## What Changed

- Add the company-scoped `agent_commentary` table, shared validation,
and idempotent migration `0310`.
- Add one transactional service and the agent-only POST route. Validate
active authority before writes or replay. Redact known credentials.
Commit a content-free audit with each new record.
- Add `submit_complaint` and `submit_suggestion` to standard, ask, and
planning modes. Keep review, revocation, and completion restrictions.
Store replay identity on the commentary row.
- Mount `complain` and `suggestion-box` by default for legacy agents.
Bundle a dependency-free Node.js stdin helper in the operational skill
and allow its POST through the sandbox bridge.
- Preserve Warp's complaint voice and suggestion guidance, with
attribution and local transport adaptations. Keep source attribution and
MIT notices in each skill's LICENSE, outside runtime instructions.
- Document custom-runtime HTTP use and database inspection. Add
real-database tests and a repeatable live Codex smoke for local and
Daytona execution.
- Pin the lagging-source migration fixture before the identity-repair
migration so later migrations preserve its regression coverage.

## Verification

- Personally ran real Codex submissions in all four environments on
2026-10-06. Local runs passed at 20:35 UTC. Daytona native passed at
20:31 UTC; Daytona legacy passed at 20:33 UTC. Each stored exactly two
rows with company, agent, run, and task attribution, wrote the
continuation marker, exited zero, created no task comments, and left
task status unchanged. Each recorded two content-free activity entries.
- Daytona used production provider hooks, real remote execution and file
transfer, the legacy queue callback bridge, and native private WebSocket
ingress. The current Linux runner was built from `abf47b595`, staged,
and verified against controller contracts. Both sandboxes were confirmed
deleted. This is a focused feedback transport smoke; it does not claim
full Runner E2E catalog or browser qualification.
- The immutable base image and Linux binary digest are recorded in [the
verification
documentation](https://github.com/paperclipai/paperclip/blob/codex/agent-commentary/doc/agent-commentary.md#verification).
The smoke script can save content-free JSON evidence. No credentials or
feedback bodies are in these reports.

| Environment | Runner | Complaint row | Suggestion row |
| --- | --- | --- | --- |
| local | legacy Codex | `59413a00-1de2-4bb1-bcc6-9c4b54c64aa6` |
`3db2364d-3e15-4f47-846f-875d3902999d` |
| local | native Codex | `5da22b5f-41df-4de5-8ba0-d9345ab01267` |
`2d5abe17-dd41-403c-a5ee-4729f2d58921` |
| daytona | legacy Codex | `27c9d0aa-8477-409f-9da0-e8ffa48dee50` |
`209681c9-d1e9-4ce1-999e-48fa07692389` |
| daytona | native Codex | `6eb001bb-4bcf-43f7-8717-f662f53dc7c3` |
`77c383d8-a997-49e5-a33e-25c70e15c0b2` |

- Run the local check with `node cli/node_modules/tsx/dist/cli.mjs
server/scripts/verify-agent-commentary-live.ts`. The documentation gives
the Daytona invocation. Both use disposable instance databases and
normal Codex provider usage.
- Repository `pnpm -r typecheck` and `pnpm build` passed after the test
extension. The build includes runner generation, contracts, and replay
checks. The smoke scripts also passed a separate TypeScript check. The
lagging-source migration regression passed. All equivalent current-head
Vitest CI shards passed. The local monolithic `pnpm test:run` invocation
was stopped after CI supplied that coverage; it did not complete
locally.
- Focused tests cover company isolation, spoofing, revoked credentials,
stale ownership, post-finish rejection, concurrent replay, conflicting
keys, atomic rollback, and deletion through existing services. Boundary
tests cover empty text, Unicode, text beyond 8,000 characters, and the
524,288-character ceiling without truncation. Mounting tests cover
Codex, Claude, and sandbox staging. Helper tests cover standalone Node
execution, stdin, invalid UTF-8, redirects, HTTP failure, and its
deadline. Privacy and bridge tests cover successful and rejected
requests.
- Instructions were compared with Warp's originals. MIT notices and
source credits live only in LICENSE files. Native tools preserve
truthful disclosure when asked, without routine announcements.
- [Full
CI](https://github.com/paperclipai/paperclip/actions/runs/37508559190)
and Greptile 5/5 passed on the earlier feature commit `5209c3501`. The
later head found the migration-fixture assumption fixed in this update.
On `8a4965164`, all 55 check contexts passed after one browser shard
rerun. Its initial reviewer signoff failure also passed an isolated
local browser run (1 test). Greptile scored that head 5/5 and identified
one smoke cleanup gap. `6ecbafb0b` fixes failed-acquisition cleanup with
four passing tests and a passing smoke-script typecheck. Fresh CI is
pending for this final test-only fix. No commentary production code
changed during verification.

## Risks

- Feedback is internally attributed. It is not anonymous. Existing
redaction removes known credentials, but agents must still omit
sensitive content. Normal provider transcripts can include their
submitted arguments.
- Default skill availability changes for existing legacy agents. Runtime
policy filtering still applies. The helper uses the existing Node.js
runtime with no extra dependencies; custom runtimes can call the HTTP
endpoint.
- Feedback is removed with its run, agent, or company. Task deletion
clears only the issue pointer. Normal database backups include the
table.
- The migration is additive and has no backfill. Writes serialize on the
active run for replay consistency. No server suggestion quota is
imposed.

## Model Used

OpenAI `gpt-6-astra` through Codex, with `xhigh` reasoning effort and a
reported 258,400-token context window. Capabilities used: repository
inspection, code execution, and live runtime verification. No subagents
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
- [ ] 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-10-06 16:14:06 -05:00

30 KiB

Raw Blame History

Capability Capability Contract

This generated contract is a self-contained derivative of the Paperclip skill, its seven references, the Paperclip Evals corpus, and the legacy MCP tool surface. It does not import or contact the Paperclip control plane.

The skill/reference inventory and eval cases are the only normative behavior sources. Paperclip does not use the legacy MCP calls as a production capability surface; all MCP names below are traceability aliases folded into normative eval rows. Their disposition, grants, assertions, and evidence contract are inherited from the target row rather than classified independently.

Baseline Counts

Skill/reference headings: 162
Eval cases: 106 across 16 groups
Total normative rows: 268
Legacy MCP aliases folded into normative rows: 42

Eval group	Cases
hb	5
co	6
st	8
cm	6
se	4
su	4
bl	5
dp	3
ix	9
ap	6
ar	4
er	9
rf	22
mh	4
rs	3
wk	8

Regeneration

pnpm --dir packages/paperclip-runner generate:capability-inventory imports the canonical baselines and rewrites every generated file.
pnpm --dir packages/paperclip-runner check:capability-inventory validates counts, uniqueness, normative dispositions, one-to-one MCP folds, required fields, and generated-file drift without requiring the external eval repository.

Skill / Reference Rows

Legacy MCP Alias Index

This is a compatibility/traceability index, not a tool catalog. “Inherited disposition” is shown only to make the normative target easy to audit.

Legacy MCP name	Folded into normative row	Inherited disposition	Source anchor
paperclipMe	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:290
paperclipInboxLite	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:296
paperclipListAgents	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:302
paperclipListSkills	eval:rf-cskill-audit-01	optional_agent_tool	packages/mcp-server/src/tools.ts:308
paperclipGetAgent	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:314
paperclipListIssues	eval:se-q-filters-01	optional_agent_tool	packages/mcp-server/src/tools.ts:323
paperclipGetIssue	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:338
paperclipGetHeartbeatContext	eval:hb-context-01	control_plane_owned	packages/mcp-server/src/tools.ts:344
paperclipListComments	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:353
paperclipGetComment	eval:hb-wake-comment-01	control_plane_owned	packages/mcp-server/src/tools.ts:366
paperclipListIssueApprovals	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:373
paperclipListDocuments	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:379
paperclipGetDocument	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:385
paperclipListDocumentRevisions	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:392
paperclipListProjects	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:402
paperclipGetProject	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:408
paperclipGetIssueWorkspaceRuntime	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:417
paperclipControlIssueWorkspaceServices	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:423
paperclipWaitForIssueWorkspaceService	eval:rf-iws-target-restart-01	optional_agent_tool	packages/mcp-server/src/tools.ts:440
paperclipListGoals	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:466
paperclipGetGoal	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:472
paperclipListApprovals	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:478
paperclipCreateApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:487
paperclipGetApproval	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:496
paperclipGetApprovalIssues	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:502
paperclipListApprovalComments	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:508
paperclipCreateIssue	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:514
paperclipUpdateIssue	eval:st-done-comment-01	always_agent_tool	packages/mcp-server/src/tools.ts:521
paperclipCheckoutIssue	eval:co-body-contract-01	control_plane_owned	packages/mcp-server/src/tools.ts:528
paperclipReleaseIssue	eval:er-release-01	control_plane_owned	packages/mcp-server/src/tools.ts:540
paperclipAddComment	eval:cm-multiline-01	always_agent_tool	packages/mcp-server/src/tools.ts:546
paperclipSuggestTasks	eval:ix-suggest-tasks-01	always_agent_tool	packages/mcp-server/src/tools.ts:553
paperclipAskUserQuestions	eval:ix-questions-01	always_agent_tool	packages/mcp-server/src/tools.ts:565
paperclipRequestConfirmation	eval:ix-confirmation-plan-01	always_agent_tool	packages/mcp-server/src/tools.ts:577
paperclipRequestCheckboxConfirmation	eval:ix-checkbox-01	always_agent_tool	packages/mcp-server/src/tools.ts:589
paperclipUpsertIssueDocument	eval:dp-plan-doc-01	always_agent_tool	packages/mcp-server/src/tools.ts:601
paperclipRestoreIssueDocumentRevision	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:612
paperclipLinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:627
paperclipUnlinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:636
paperclipApprovalDecision	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:646
paperclipAddApprovalComment	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:668
paperclipApiRequest	eval:rf-api-404-report-01	optional_agent_tool	packages/mcp-server/src/tools.ts:677

Capability	Primary disposition	Source anchor
skill:skills/paperclip/SKILL.md:paperclip-skill:10	optional_agent_tool	skills/paperclip/SKILL.md:10
skill:skills/paperclip/SKILL.md:terminology:14	optional_agent_tool	skills/paperclip/SKILL.md:14
skill:skills/paperclip/SKILL.md:authentication:20	control_plane_owned	skills/paperclip/SKILL.md:20
skill:skills/paperclip/SKILL.md:conversation-tasks:32	optional_agent_tool	skills/paperclip/SKILL.md:32
skill:skills/paperclip/SKILL.md:server-verified-external-chat-turns:49	control_plane_owned	skills/paperclip/SKILL.md:49
skill:skills/paperclip/SKILL.md:the-heartbeat-procedure:89	optional_agent_tool	skills/paperclip/SKILL.md:89
skill:skills/paperclip/SKILL.md:generated-artifacts-and-work-products:198	always_agent_tool	skills/paperclip/SKILL.md:198
skill:skills/paperclip/SKILL.md:status-quick-guide:246	control_plane_owned	skills/paperclip/SKILL.md:246
skill:skills/paperclip/SKILL.md:monitors-and-watchers-say-only-what-you-actually-scheduled:256	optional_agent_tool	skills/paperclip/SKILL.md:256
skill:skills/paperclip/SKILL.md:delegating-review-tasks:269	always_agent_tool	skills/paperclip/SKILL.md:269
skill:skills/paperclip/SKILL.md:managing-a-user-s-inbox:280	control_plane_owned	skills/paperclip/SKILL.md:280
skill:skills/paperclip/SKILL.md:issue-dependencies-blockers:288	control_plane_owned	skills/paperclip/SKILL.md:288
skill:skills/paperclip/SKILL.md:requesting-board-approval:313	optional_agent_tool	skills/paperclip/SKILL.md:313
skill:skills/paperclip/SKILL.md:issue-thread-interactions:334	optional_agent_tool	skills/paperclip/SKILL.md:334
skill:skills/paperclip/SKILL.md:standalone-decisions:363	optional_agent_tool	skills/paperclip/SKILL.md:363
skill:skills/paperclip/SKILL.md:mcp-tool-approval-gates:467	optional_agent_tool	skills/paperclip/SKILL.md:467
skill:skills/paperclip/SKILL.md:niche-workflow-pointers:509	optional_agent_tool	skills/paperclip/SKILL.md:509
skill:skills/paperclip/SKILL.md:cases:519	optional_agent_tool	skills/paperclip/SKILL.md:519
skill:skills/paperclip/SKILL.md:company-skills-workflow:524	optional_agent_tool	skills/paperclip/SKILL.md:524
skill:skills/paperclip/SKILL.md:routines:535	optional_agent_tool	skills/paperclip/SKILL.md:535
skill:skills/paperclip/SKILL.md:issue-workspace-runtime-controls:546	optional_agent_tool	skills/paperclip/SKILL.md:546
skill:skills/paperclip/SKILL.md:proposing-credentials-safely:553	optional_agent_tool	skills/paperclip/SKILL.md:553
skill:skills/paperclip/SKILL.md:reading-granted-secrets:560	optional_agent_tool	skills/paperclip/SKILL.md:560
skill:skills/paperclip/SKILL.md:critical-rules:586	optional_agent_tool	skills/paperclip/SKILL.md:586
skill:skills/paperclip/SKILL.md:comment-style-required:607	always_agent_tool	skills/paperclip/SKILL.md:607
skill:skills/paperclip/SKILL.md:update:639	optional_agent_tool	skills/paperclip/SKILL.md:639
skill:skills/paperclip/SKILL.md:task-documents-and-deliverables:649	always_agent_tool	skills/paperclip/SKILL.md:649
skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:663	optional_agent_tool	skills/paperclip/SKILL.md:663
skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:694	optional_agent_tool	skills/paperclip/SKILL.md:694
skill:skills/paperclip/SKILL.md:searching-issues:723	optional_agent_tool	skills/paperclip/SKILL.md:723
skill:skills/paperclip/SKILL.md:full-reference:733	optional_agent_tool	skills/paperclip/SKILL.md:733
skill:skills/paperclip/SKILL.md:conversational-confirmation-answers:737	always_agent_tool	skills/paperclip/SKILL.md:737
skill:skills/paperclip/SKILL.md:incidental-feedback:754	optional_agent_tool	skills/paperclip/SKILL.md:754
skill:skills/paperclip/references/api-reference.md:paperclip-api-reference:1	optional_agent_tool	skills/paperclip/references/api-reference.md:1
skill:skills/paperclip/references/api-reference.md:response-schemas:9	optional_agent_tool	skills/paperclip/references/api-reference.md:9
skill:skills/paperclip/references/api-reference.md:agent-record-get-api-agents-me-or-get-api-agents-agentid:11	optional_agent_tool	skills/paperclip/references/api-reference.md:11
skill:skills/paperclip/references/api-reference.md:company-portability:44	optional_agent_tool	skills/paperclip/references/api-reference.md:44
skill:skills/paperclip/references/api-reference.md:issue-with-ancestors-get-api-issues-issueid:110	optional_agent_tool	skills/paperclip/references/api-reference.md:110
skill:skills/paperclip/references/api-reference.md:issue-update-response-patch-api-issues-issueid:196	optional_agent_tool	skills/paperclip/references/api-reference.md:196
skill:skills/paperclip/references/api-reference.md:blocker-diagnostics-get-api-issues-issueid-diagnostics-blockers:238	control_plane_owned	skills/paperclip/references/api-reference.md:238

30 KiB Raw Blame History