Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-28 12:04:41 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
05f7079ecb2ee28d64715fd18e60b43e2d2fa989
PaperClipAI/maps/agent-access-map/tasks.md
T
DottaandPaperclip 3bbc2104b6 docs: map missing product and operator capabilities (#16990) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The feature map records product entry points and verification
recipes.
> - The paired agent access map records APIs and permission boundaries
for the same capability IDs.
> - The new index in #16987 made several missing capabilities easier to
find.
> - Those gaps hid existing assistant, privacy, cost, and operator
workflows.
> - This pull request adds 15 capabilities with source references, test
scope, and manual checks.
> - Readers can find these workflows without treating documentation or
structural checks as live proof.

## Linked Issues or Issue Description

Refs: #16987. Related map work: #16025 and #16214. A search of related
pull requests found no duplicate of these additions.

**Issue type**

Missing documentation.

**Where is the issue?**

`maps/feature-map/` and `maps/agent-access-map/`.

**What's wrong?**

The maps omit public assistant MCP connections, private task and project
sharing, subscription fees, cost-recording recovery, agent API keys,
keyboard entry points, and several operator CLI workflows.

**Suggested fix**

Add product recipes and matching access records. Show the full
capability IDs in the README index and each page. Keep the existing ID
format and all 175 existing IDs. Exclude AI account pools.

## What Changed

- Add the `assistant-connections` family with setup, consent, device
login, client use, and revocation.
- Add `tasks/privacy`, `projects/privacy`,
`budgets-costs/subscriptions`, and `budgets-costs/accounting-recovery`.
- Add `agents/api-keys`, `agents/managed-agent-setup`, and
`navigation-preferences/command-palette`.
- Add `cli-operations/feedback-export`, `chat-channels/outbound-email`,
and `instance-operations/runtime-setup`.
- Pair all 15 additions with access rules, source evidence, manual
checks, and explicit coverage gaps. Update the visible index to 35
families and 190 capability IDs.
- Add cross-links from existing access, connection setup, search, and
CLI recipes. Do not change the schema or add AI account pools.
- Clarify that the task Share sheet displays direct and inherited
access. Manage inherited access at its ancestor or project source.

## Verification

- `node scripts/check-maps.mjs` passes: 35 areas and 190 paired
capability IDs, with valid references and contract fields.
- `node --test scripts/check-maps.test.mjs
scripts/storybook-feature-index.test.mjs` passes: 17 tests.
- `node scripts/storybook-feature-index.mjs` and `git diff --check`
pass.
- A comparison with the base confirms all 175 existing IDs remain and
exactly the intended 15 IDs were added. The README index matches the
discovered feature metadata.
- `node scripts/storybook-catalog.mjs` cannot run because this checkout
lacks `storybook/internal/csf-tools` and installed workspace
dependencies.
- `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build` were attempted.
All stopped before their task ran: the pnpm 9.15.4 bootstrap could not
fetch and verify its registry packages in this environment.
- Source review covers the documented UI, CLI, routes, services, and
existing tests. No live browser, provider, or authorization journey was
run. New access records remain `baseline`, `source-only`, and `not-run`.
- Greptile and the Paperclip reviewer both rate current commit
`bb8eb797b0a1dc26256faf2f0e57cbe7abc9adcf` 5/5. The inherited-access
review thread is resolved.
- [GitHub
CI](https://github.com/paperclipai/paperclip/actions/runs/39466772379)
passes for that commit, including typecheck, build, unit tests, Runner
checks, and browser tests. Browser shard 7 passed after one retry for a
runner shutdown. All PR checks are successful, neutral, or skipped.

## Risks

- Low runtime risk: this change only edits maps. No application
behavior, API, dependency, or schema changes.
- Source-reviewed recipes can drift or miss deployment-specific
behavior. The records state their limits and require live checks before
a capability is marked verified.

> 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, model ID `gpt-6.1-sol`, 475,000-token context window,
xhigh reasoning effort, 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

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-10-20 12:47:41 -05:00

245 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Task creation and lifecycle — agent access
Product map: [Task creation and lifecycle](../feature-map/tasks.md).
Feature ID: `tasks`.
Review date: 2026-10-12. Source commit: `58e16dbddfc9c8d0cf60867f9d9847f0feda055b`.
Native REST transport reconciled in this change; see the
[shared transport contract](README.md#native-rest-transport).
This is a source-reviewed baseline of representative operations and known gaps.
Each capability needs operation-level review before its entire scope can be
qualified. No live agent execution is claimed. Follow the [map contract](../README.md)
for format, permission checks, evidence and maintenance.
## `create`
Capability ID: `tasks/create`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/companies/{companyId}/issues`.
Agent access: `available` — Native create_task; REST / CLI / MCP.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
and lifecycle rules. Ordinary Board comments preserve queued/running retries;
only a parked retry can be superseded. Explicit Stop/Interrupt retain their
existing actor and execution authority. Agent comment tools do not acquire Board
identity or cancellation authority through this behavior.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Creation is implemented; agent/user assignment and attachments may need
narrower/different APIs.
## `organize`
Capability ID: `tasks/organize`.
`GET /api/companies/{companyId}/issues/summaries?ids=...` reads up to five exact
UUIDs and returns only navigation summaries. Normal company and task-read
permissions apply to ordinary agent REST calls; task-bridge keys are denied.
Hidden, missing, foreign and private inaccessible IDs are omitted without an
existence disclosure. No dedicated CLI/native tool is added. Embedded database
route tests cover same-company agent access and company/task-bridge denials;
this does not establish a live native `call_api` journey.
The issue-list API accepts optional `includeAgentCreatedTasks`; false restricts
independent results to human creation before search/pagination. Omission retains
existing agent/API behavior. `includeParticipatedTasks=true` requires a board user
and retains only that authenticated user's existing participation as a creation
visibility exception. Company/private-task access checks still apply. Collection
preferences and hierarchy presentation are browser state, not additional authority.
Source-reviewed behavior; live agent access verification remains separate.
All `chat_channel` origins count as bot-created for creation visibility, including
human-initiated conversations. Existing inbox participation remains independent.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/companies/{companyId}/issues`.
Agent access: `available` — Native search_tasks; REST / CLI; UI grouping/navigation
state separately.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
and lifecycle rules.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Search/filter API exists; sorting/grouping/presentation defaults are not
necessarily shared server preferences.
## `properties`
Capability ID: `tasks/properties`.
Review: `baseline`.
Agent REST callers can promote a prepared backlog task with
`PATCH /api/issues/{id}` and exactly `{ "status": "todo", "expectedStatusVersion": N }`.
The optional nonnegative integer version comes from the current task response.
The server checks both the version and backlog state under the task row lock;
status or ownership changes, including changes back to their earlier values,
return `409` without promoting or waking the task. Mixed mutation fields return
`422`. Existing company, task, assignment and run authority still apply.
Route and real-PostgreSQL service tests cover the contract; no live agent journey
or dedicated native tool is claimed.
API: `present` — representative operation IDs:
- `PATCH /api/issues/{id}`.
- `PUT /api/issues/{id}/title`.
Agent access: `available` — Native set_task_title/reassign_task/set_dependencies and
set_task_monitor; `call_api` for REST-authorized fields; agent REST. Monitor
scheduling is a dedicated native tool, not a generic `call_api` operation.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
and lifecycle rules. A legacy run can assign its own task to a human without
cancelling itself only with its signed run token and matching active run, agent,
company and task. The outgoing run cannot mutate its human-owned task afterward,
including through a late update already admitted before the handoff. Agent keys,
native runs, board reassignment and transfers to
another agent retain verified-stop requirements.
Native monitors require standard work mode and an agent-owned task in progress
or review. The responsible user's current permissions also apply. A malformed
request is rejected before mutation; bounded schema guidance lets the provider
correct it without exposing submitted values. Receipt replay never re-arms a
consumed schedule.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability. Focused route
regressions in [ownership tests](../../server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts)
cover a human handoff and stop enforcement for other actors, runtimes and targets;
they use mocked services and do not claim live execution proof.
Queue and HTTP/2 sandbox callbacks admit `GET /api/issues/{id}/diagnostics/wakes`
and `POST /api/issues/{id}/monitor/check-now`. The controller still checks task
read access or monitor-management permission and assignment ownership. Recovery
resolution and scheduled-retry controls remain outside this bridge surface.
Monitor verification: submit flat scheduling fields, observe the schema rejection
and unchanged task, then retry with the nested `monitor` object and the same
idempotency key. Inspect the saved schedule and audit, yield, and verify exactly
one `issue_monitor_due` wake. [Scheduler integration coverage](../../server/src/__tests__/issue-monitor-scheduler.test.ts)
uses real PostgreSQL, the native tool authority, and the heartbeat scheduler with
a no-op process agent. It does not prove live model recovery.
Monitor deferral diagnostics: an unresolved execution-recovery hold keeps a due
schedule intact and prevents execution. Read `issue.monitor_deferred` activity
for the safe blocker cause; unexpected dispatch failures record
`issue.monitor_dispatch_failed`. Repeated identical diagnostics are throttled for
five minutes. The scheduler regression proves that a held source does not replay
and that clearing the hold permits one later wake. This is local PostgreSQL
evidence, not live provider recovery.
Native timer dispatch also waits for unfinished finalization after a terminal
provider run. Recovery may use that run's scheduling receipt and the matching
admitted successor as historical delivery evidence. It does not grant new
execution authority or clear a successor's ownership. Missing receipts,
unadmitted wakes, and unfinished workspace persistence remain held.
An accepted result may settle into a schedule that expired during recovery;
the scheduler applies its existing expiry policy afterward. This does not
authorize a new provider result to wait on an expired or exhausted monitor.
Gaps: Dedicated tools differ in scope and fields. Generic `call_api` forwards
status, assignment and dependency fields to existing route authorization.
## `discussion`
Capability ID: `tasks/discussion`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/issues/{id}/comments`.
- `POST /api/companies/{companyId}/issues/{issueId}/attachments`.
Agent access: `available` — Native report_progress/comment_on_task/register_deliverable;
REST / CLI / MCP.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
and lifecycle rules.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Other-task comments and active-task progress have separate scopes. Generic
`call_api` forwards explicit reopen/resume/interrupt fields to the existing route
checks; it cannot impersonate a user.
## `completion`
Capability ID: `tasks/completion`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `PATCH /api/issues/{id}`.
Agent access: `available` — Native paperclip_finish/paperclip_block through runner
protocol; agent REST / native `call_api` disposition under route permissions.
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
and lifecycle rules.
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
reviewed commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: The server governs whether a reported result becomes done/review/blocked.
Generic lifecycle PATCH uses existing REST authorization, checkout and approval rules.
## `privacy`
Capability ID: `tasks/privacy`.
Review: `baseline`.
API: `present` — POST /api/companies/{companyId}/issues and PATCH /api/issues/{id} accept permitted visibility changes; GET /api/issues/{id}/privacy-constraints; GET and POST /api/issues/{id}/access-grants; POST /api/issues/{id}/access-grants/{grantId}/revoke.
Agent access: `partial` — eligible task reads and a permitted restriction to private are available through agent REST/native `call_api`, subject to current mutation and run authority. Grant inspection/management and widening task access require the authorized board identity; catalog actor labels do not override those route checks.
Policy: Company access and issue:read precede management checks; inaccessible tasks return not found. Grant/privacy management requires the responsible user, creator, human assignee, active company owner/admin, instance admin, or local implicit board. Grant targets must be active company users or company agents. A shared reader is not a grant manager. Private inheritance flows down descendants, not upward or across siblings. Agent access intersects the responsible user’s authority. Publishing obeys parent/project constraints; a private standalone task needs a responsible user. Mutations retain activity and task lifecycle checks.
Evidence: `source-only` — reviewed at `9ef434fe79c57d976b8b03b14c5242db270b8320`. [Privacy actions](../../ui/src/components/IssuePrivacyActions.tsx), [share sheet](../../ui/src/components/IssueShareSheet.tsx), [issue routes](../../server/src/routes/issues.ts), and [authorization](../../server/src/services/authorization.ts).
Verification: `not-run` — Create private fixtures as ordinary authenticated people, then compare discovery, direct reads, inherited child access, and inaccessible metadata before sharing and after revocation. Reject a shared reader’s grant management, cross-company or invalid targets, grants on open tasks, and agent publishing/sharing. Assert the permitted agent restriction using its actual current run and responsible-user context.
Gaps: The native API fallback must be admitted in the tested run and mode. Full descendant, personal-project, race, and responsible-user combinations need live acceptance; source-reviewed permission branches do not establish all variants.
Reference in new issue View Git Blame Copy Permalink