Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-23 17:33:51 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
572bef4ba7679451ac1543db25cb8ebd533bf919
PaperClipAI/maps/agent-access-map/chat-channels.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

289 lines
16 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.
# External chat and email conversations — agent access
Product map: [External chat and email conversations](../feature-map/chat-channels.md).
Feature ID: `chat-channels`.
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.
## `providers`
Capability ID: `chat-channels/providers`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/companies/{companyId}/chat-endpoints`.
Agent access: `restricted` — Board setup APIs; native connection request can ask for
setup.
Policy: Endpoint management/identity linking requires a board user; delivery is
server-owned and agent tools use scoped assignments.
Evidence: `source-only` — [implementation](../../server/src/routes/chat-channels.ts#L75)
at the reviewed commit above.
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Provider installation and account enrollment are not available to an ordinary
agent actor.
Speko UI reconciliation (2026-10-13): experimental voice setup uses the same
board-managed endpoint boundary. Source review follows the merged voice runtime
and the UI integration; live provider qualification is still separate.
## `identity`
Capability ID: `chat-channels/identity`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/chat-identity-links/confirm`.
Agent access: `restricted` — Human identity-link flow.
Policy: Endpoint management/identity linking requires a board user; delivery is
server-owned and agent tools use scoped assignments.
Evidence: `source-only` — [implementation](../../server/src/routes/chat-channels.ts#L75)
at the reviewed commit above.
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Identity linking requires a signed-in board user, rollout admission and
provider checks at the HTTP route. Native `call_api` preserves these permissions.
## `conversation`
Capability ID: `chat-channels/conversation`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/chat-endpoints/{endpointId}/conversations/{conversationId}/publications`.
Agent access: `partial` — Assigned-agent reply pipeline; native completion; provider
tools where assigned.
Policy: Endpoint management/identity linking requires a board user; delivery is
server-owned and agent tools use scoped assignments.
Evidence: `source-only` — [implementation](../../server/src/routes/chat-channels.ts#L75)
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: Normal agent replies work through server delivery. Explicit endpoint publication
APIs are board management paths.
Publication, provider-reply, and form-open 403/permission errors fail the rejected
operation without removing unrelated assigned channel tools. Confirmed
authentication failures still put the endpoint in attention, which blocks tool
admission and provider sends; connection enabled intent is retained. Known
resource denials and explicit revocation keep their narrower or installation-wide
stops. PostgreSQL provider fixtures verify discovery after 403 and rejection after
401, including signed installation removal after a 401; they do not establish
live GitHub credential recovery.
GitHub publication recovery (2026-10-14): assigned-agent `submit_review`, `comment`,
and `update_comment` calls reuse their run-, task-, endpoint-, and argument-bound
publication on an exact retry. Identity uses the complete durable request rather
than the shortened audit preview. A changed suffix, changed nested entry, or
missing publication cannot authorize another write. Exact retries only read the
receipt; the worker owns pending provider retries. Fresh gateway policy and provider authority remain
required. The durable worker resumes transient failures after restart and stops
at its retry cap, revoked authority, or a superseded head. A pending receipt is
not task completion. Source:
[publication service](../../server/src/services/chat-github-reviews.ts) and
[gateway](../../server/src/services/tool-gateway.ts). Verification uses
PostgreSQL-backed provider fixtures; this entry does not claim live provider
qualification for the new retry path.
GitHub main-response identity (2026-10-19): PR requests share a company-, App-,
repository- and PR-bound comment. Agents still supply no comment destination.
Current sender, assignee, repository and publication authority are checked before
edits, including maintenance failure notices. Leading mentions for another
recipient are filtered before task work; explicit mentions of this bot still
follow normal access checks. Provider-fixture coverage is not live GitHub proof.
Native terminal reconciliation resolves the accepted run identity through the
existing chat provenance resolver; an older run's reply cannot complete a newer
request merely because both requests share the same PR comment.
Speko browser sessions use `POST /api/companies/{companyId}/voice-sessions`,
with GET inspection/notification and POST `/{sessionId}/end` operations below
that collection. These routes require board identity; ordinary agent credentials
cannot start a private voice session. Start and notification also require the
experimental chat-connectors gate. Signed provider callbacks use the separate
voice-webhook routes and their session capability. Evidence: `source-only` —
[voice routes](../../server/src/routes/voice-sessions.ts). No live browser answer
retrieval or telephone playback is established by the UI fixtures.
Slack's **Require at-mention** policy applies to channel messages and channel
thread replies, including queued work. DMs are exempt from mention checks;
endpoint availability, **Allow direct messages**, and sender authorization still
apply. Top-level DM replies retain their linear conversation destination. Source:
[admission](../../server/src/services/chat-channels.ts) and
[queued run policy](../../server/src/services/durable-chat-wakeup.ts). Live Slack
verification of this exemption remains separate from provider-fixture coverage.
Slack eyes acknowledge the authorized task/comment commit before attachment
preparation or scheduler acceptance. This server-owned receipt grants no agent
authority. Generation/credential fencing, durable retries and exact-source final
cleanup still apply. PostgreSQL fixtures block attachments, subscription and
wakeup independently to verify that none gates the reaction; live Slack latency
remains a separate check. See [receipt worker](../../server/src/services/chat-channels/receipt-reactions.ts).
Controller-owned receipt reactions accept the SDK's empty thread timestamp for
linear DMs. Channel IDs and source message timestamps remain validated. This
does not add an agent tool or change sender, task, or credential authorization.
The pinned SDK transport regression is covered in
[receipt tests](../../server/src/services/chat-slack-receipts.test.ts); live
acknowledgement speed needs a separate provider test.
Slack assignment and tool discovery bound concurrent endpoint preparation to
two. Every endpoint keeps the live task, company, agent and linked-user checks;
403 denials omit only that endpoint. Preparation waits for both active checks
before it returns an ordered result or propagates an error. Tool authority reads
the current bot token without resolving unrelated webhook credentials. See the
[real-database preparation controls](../../server/src/__tests__/slack-tool-preparation.test.ts)
and [batch failure controls](../../server/src/services/connectors/slack-endpoint-preparation.test.ts).
These local controls do not establish live Slack latency or provider access.
Native tool gateways use the durable run task binding for discovery and policy
checks, with legacy JSON task fields as a fallback. GitHub and Slack follow
accepted request provenance across task continuations. GitHub can retain the
originating conversation after a board follow-up from the same accepted user.
An inherited origin cannot cross a task, agent, company, or requester boundary.
Cycle checks reject invalid history without a fixed limit on valid continuations.
Endpoint settings, linked identity, tool profiles, and invocation policy still
apply on each call. The native tool contract rotates older provider sessions so
an empty retained catalog is not reused. PostgreSQL fixtures cover discovery,
review publication, Slack reads, and revocation in
[channel integration](../../server/src/__tests__/chat-channels.integration.test.ts)
and [provenance controls](../../server/src/services/chat-channels/run-origin.test.ts).
The [voice gateway fixture](../../server/src/__tests__/voice-session-store.integration.test.ts)
also verifies durable task binding for a later personal callback invocation.
Failure replies cannot replace final answers inherited from an earlier run.
These fixtures do not prove live provider delivery.
Catalog authorization projection (2026-10-17): tool discovery uses the same live
service-owned task, company, agent, requester, endpoint and credential checks as
full authority resolution. It omits the revision digest and search-action token,
which catalog descriptors do not consume. Connector assignments and governed
operations retain full revision resolution; invocation policy is still checked
by the gateway. Registry replacement and missing-service controls are in
[authority registration tests](../../server/src/services/connectors/slack-authority.test.ts).
This is a source and local-database contract; hosted latency needs live evidence.
New conversations resolve typed project/workspace defaults from their endpoint
and destination under the task-creation transaction. Defaults do not authorize
private sources: admission checks the linked user's authority and assigned agent.
An existing conversation keeps its task binding. See
[creation service](../../server/src/services/chat-channels.ts) and
[defaults contract](../../packages/shared/src/types/chat-channels.ts).
## `attachments`
Capability ID: `chat-channels/attachments`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/issues/{id}/attachments`.
- `POST /api/companies/{companyId}/issues/{issueId}/attachments`.
Agent access: `partial` — Native register_deliverable / attachment tools when admitted;
agent REST; server-owned delivery.
Policy: Endpoint management/identity linking requires a board user; delivery is
server-owned and agent tools use scoped assignments.
Evidence: `source-only` — [implementation](../../server/src/routes/chat-channels.ts#L75)
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: Uploading/registering is supported. Provider delivery status and board replay are
separate operations.
## `lifecycle`
Capability ID: `chat-channels/lifecycle`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/chat-endpoints/{endpointId}/activity`.
- `PATCH /api/chat-endpoints/{endpointId}`.
- `PUT /api/chat-endpoints/{endpointId}/resources` configures destination defaults.
Agent access: `restricted` — Board lifecycle APIs; agent requests repair when blocked.
Policy: Endpoint management/identity linking requires a board user; delivery is
server-owned and agent tools use scoped assignments.
Evidence: `source-only` — [implementation](../../server/src/routes/chat-channels.ts#L75)
at the reviewed commit above.
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Activity/repair/replay/disable use board endpoint access, not the agent's ability
to reply.
Endpoint/destination execution defaults use the same board-only management
boundary. Agents select an authorized workspace for their current task through
the [workspace APIs](workspaces.md), rather than editing channel configuration.
Speko callback preferences, incoming phone configuration/approval, and call
history use the company-scoped `voice-callbacks`, `voice-phone`, and
`voice-history` routes. Their UI controls do not grant agents board authority.
See [voice routes](../../server/src/routes/voice-sessions.ts); service-level
caller/session permissions and real provider delivery need separate verification.
GitHub review summary headings use the bot display name. Checks remain
independently scoped by GitHub App and endpoint/PR/commit identity.
## `outbound-email`
Capability ID: `chat-channels/outbound-email`.
Review: `baseline`.
API: `present` — GET /api/companies/{companyId}/email/inboxes; POST /api/companies/{companyId}/email/send for both send/reply; GET /api/companies/{companyId}/email/tasks/{issueId}; GET /api/companies/{companyId}/email/deliveries/{publicationId}. Administrative uncertain-outcome resolution uses POST /api/companies/{companyId}/email/deliveries/{publicationId}/resolve.
Agent access: `partial` — the assigned agent can use the email REST/CLI path with its actual active run and admitted email.send/email.reply policy. Board writers use their own credential authority. Availability of a CLI or scenario email tool does not establish that a native run has that tool binding or generic fallback admitted.
Policy: Agent sends require ownership of the inbox and source task, task read access, an available agent within budget, a running task run that owns execution/checkout, standard work mode, and no restricted external execution. Active endpoint, connection, credential access, and email.send/email.reply policy are rechecked. Authenticated board sends require active company membership and credential access; viewer sends additionally require instance-admin status. Local implicit authority skips the membership check. Agent reads retain task/inbox/company checks; board thread/delivery reads use the route’s company-access boundary. Delivery resolution requires board tools:manage_connections or existing elevated operator authority, not ordinary agent access.
Evidence: `source-only` — reviewed at `9ef434fe79c57d976b8b03b14c5242db270b8320`. [Email CLI](../../cli/src/commands/client/email.ts), [request schema](../../packages/shared/src/validators/email.ts), [email routes](../../server/src/routes/email.ts), and [email authority/publication](../../server/src/services/email-channels.ts).
Verification: `not-run` — Use the actual permitted writer and run to create one child/publication, confirm recipient delivery and an exact-message reply, and repeat idempotent requests without duplicate sends. Assert run/owner/mode/budget/company/credential/attachment denials and separate read access. Inspect the provider before resolving an unknown write outcome; a 202 or queued publication alone is not proof of delivery.
Gaps: Real AgentMail transport, recipient delivery, and each native tool binding still need live proof. Controlled provider receipts and inbound-reply recipes do not establish a newly initiated external email journey.
Reference in new issue View Git Blame Copy Permalink