DottaandPaperclip
df4ee06e2f
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Skills can track a branch in an authorized GitHub repository. > - Sources previously offered only a default-branch repair action. > - People need to select a listed branch or enter a branch that GitHub has not listed. > - The server must validate the selected ref with the caller's authorized connection. > - This pull request connects the approved branch picker to production APIs. > - Installed skills remain usable while the source changes its tracked ref. ## Linked Issues or Issue Description **Subsystem affected** Skills UI, shared API contracts, GitHub source services, and agent API discovery. **Problem or motivation** The default-branch repair action does not let people choose another branch. The settings service also validates the old ref when a caller supplies a new ref other than HEAD. A missing tracked branch can prevent connection repair even when the selected account has repository access. **Proposed solution** Load a bounded branch list with the authorized connection. Mark the default branch. Search listed branches or accept a typed ref. Validate the selected ref before saving. Keep the chosen value after a load error, invalid ref, or concurrent update. Save the selected connection and branch together during connection repair. **Alternatives considered** A default-branch button does not support a named branch. A text field alone does not help people find the repository default or available branches. **Roadmap alignment** This improves the existing Skills source manager. It does not add a new skill import system. **Additional context** Refs #16066 and #16256. This is the production implementation of the approved branch-selection Storybook journeys. ## What Changed - Add an authorized branch-list endpoint and shared response/query types. Register it in agent API discovery. - Validate the requested ref, including the returned commit SHA. Preserve source leases, revision checks, project ownership, skill identities, selections, and installed versions. - Add the searchable branch picker to Sources and connection repair. Allow typed refs during branch discovery and after discovery fails. - Keep save errors in the dialog. Retain the selected branch through a concurrent source update. - Use the production components and API client in Storybook. Add keyboard, touch, loading, retry, invalid-ref, connection-repair, and concurrent-update browser journeys. - Update product documentation and the feature/access maps. ## Verification - Red/green: two new database regressions fail against the previous service and pass against the implementation. - Linux database/service suite: 85 tests passed. This includes source visibility, human/agent authorization, selected connections, immutable versions, and invalid refs. - Rebased branch and review fixes: 94 focused UI, route, branch-validation, and fixture tests passed. Two conflict-message regressions and the stale-retry fixture regression fail before the fix and pass after it. - Storybook build passed. All 26 focused browser journeys passed. - Repository typecheck and build passed. Final UI typecheck passed after the review fixes. - The full local Vitest run was interrupted when the checkout and its dependencies disappeared. It reported missing working-directory/Postgres files and worker startup errors. Its two timed-out tests pass after the checkout was restored. The complete CI suite passed on the final head, `cf5d4c8f0a`: [CI run](https://github.com/paperclipai/paperclip/actions/runs/38571068332). One unchanged workspace timestamp test required a single rerun. Its release-minus-one-millisecond value can equal the original confirmation time. The rerun passed. - Live acceptance passed on implementation head `5dd935bf14` in an isolated macOS arm64 instance with Node 24.21.0 and an authorized private GitHub repository. The UI loaded the actual default branch, saved branch and selected connection together, and preserved the installed skill/version IDs after reload. An invalid typed ref retained the draft and showed the provider error. A valid typed HEAD ref then saved successfully. The owned runtime and database were stopped after the test. Focused unit, Linux database, and browser suites passed again after the error-handling review fixes. - Greptile reviewed final head `cf5d4c8f0a` at 5/5. Both review threads are resolved; the fresh review has no remaining findings. - Token gates and map/catalog checks passed. - Review entry points: `Skills / Project repository skills / 03 Branch selection components` and `04 Branch selection journeys`. Run `pnpm storybook` to inspect them. - Browser command: `pnpm exec playwright test --config tests/storybook-visual/playwright.config.ts tests/storybook-visual/skill-source-branch-selection.spec.ts tests/storybook-visual/project-repository-skills.spec.ts`. - Manual check: open an independent GitHub source, choose a new branch, select the default or type a ref, save, and reload. Try an invalid ref and confirm the selection remains in the dialog. For a project-bound source, change its ref in project settings. ## Risks - GitHub discovery is bounded to 100 listed branches. The default branch is always included. Typed refs remain available. - A source can change while the dialog is open. The API rejects a stale revision and the UI keeps the draft for retry. - A ref change schedules the existing refresh pipeline. Installed versions remain available until a successful refresh imports new content. - No database migration or credential storage change is required. Existing HEAD requests remain supported. ## Model Used OpenAI Codex, GPT-6 family. The serving model's exact identifier and context-window size are not exposed in this session. Used reasoning, repository tools, code execution, and browser tools. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (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>
8.2 KiB
Skill discovery, authoring, and policy — agent access
Product map: Skill discovery, authoring, and policy.
Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b.
Native REST transport reconciled in this change; see the
shared transport contract.
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 for format, permission checks, evidence and maintenance.
discovery
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/skills.POST /api/companies/{companyId}/skills/import.
Agent access: available — REST / native call_api / CLI skills and sources.
Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.
Evidence: source-only —
implementation 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: Installation/import is governed by company skill policy, not inferred from an agent's role name.
authoring
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/skills.PATCH /api/companies/{companyId}/skills/{skillId}/files.
Agent access: available — Native create_skill/update_skill for single-file operations;
REST for other files/metadata.
Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.
Evidence: source-only —
implementation 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: Writable/fork policy and expected version apply. Native helpers intentionally support a narrower shape than full API.
versions
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/skills/{skillId}/versions.
Agent access: available — REST / native call_api / CLI skills.
Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.
Evidence: source-only —
implementation 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: Revision metadata has an API; pinned execution skill versions and installed latest are distinct.
policy
Review: baseline.
API: present — representative operation IDs:
PUT /api/companies/{companyId}/skill-policy.POST /api/agents/{id}/skills/sync.
Agent access: partial — REST / native call_api under users:manage_permissions or
target configuration policy.
Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.
Evidence: source-only —
implementation 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: Policy administration has an explicit agent grant branch; assigning agent skills also checks the target's config authority.
testing
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/skills/{skillId}/test-runs.
Agent access: available — Permitted agent REST / native call_api creation, control
and history; no dedicated CLI test command found.
Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority.
Evidence: source-only —
implementation 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: No dedicated native orchestration binding; generic REST calls retain skills.test policy, task-assignment authorization, responsible-user intersection and admitted skill-test JWT scope.
Project-source API additions: GET /api/companies/{companyId}/skill-sources/project-repositories,
POST /api/companies/{companyId}/skill-sources/adopt-project with workspaceId, and
PATCH /api/companies/{companyId}/skill-sources/{sourceId}/settings with expected revision
and update/connection preferences. trackingRef accepts a branch or explicit ref;
"HEAD" keeps default-branch tracking. GET /api/companies/{companyId}/skill-sources/{sourceId}/branches
returns a bounded branch list and the default branch, with optional connectionId for
connection repair. It requires source access and skills.edit, and reads only through
the caller's authorized GitHub grant. Saving validates the requested ref before changing
an independent source; active project bindings must be edited through their
project configuration. Responses identify branch, connection, or retry repair and distinguish
queued imports from imports under an active worker lease. Native API discovery uses the OpenAPI registration.
Project-derived read/use permission follows current project authorization, with access through either originating project. File/version reads, source metadata, mutations, editable copies, tests and runtime delivery retain that boundary. Unattended refresh uses the revalidated setup identity and connection, not the requesting agent's token. These additions need actual permitted/denied agent-run acceptance; service tests alone are not live credential proof.
Direct GitHub source imports share the project setup-identity boundary. API-key agents may import permitted public content, but their responsible-user field does not authorize unattended credential use. They need human connection repair for automatic refresh. Authenticated agent runs derive the setup person from the persisted active run. Legacy agent activity without a matching run cannot recover a refresh person. Route and database tests cover these distinctions; this addition makes no new live-provider acceptance claim.
Initial project imports check skills.import before provider reads; denied jobs do not retry automatically. Deferred jobs remain durable behind per-project and company admission limits. Scheduled refresh compares immutable tree identity and uses a persistent work allowance; manual refresh still requires its existing policy/access checks. These limits grant no content or execution access.
Agent repository setup preserves the active run's selected GitHub connection/grant IDs. Missing selections require human repair; the worker never searches the responsible person's other grants for an agent-created source.
Initial automatic imports reserve company work credits before provider reads. Failures retain the reservation; completed jobs cannot replenish the queue's work allowance. Jobs remain durable and resume as company credits refill.