DottaandPaperclip
4460785534
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents use skills imported from project repositories.
> - Large repositories fall back to isolated skill folders.
> - That fallback drops shared files and turns advisory links into
import failures.
> - This pull request retains bounded referenced files and keeps missing
references advisory.
> - Users can import valid skills such as test-audit without editing the
source repository.
## Linked Issues or Issue Description
Refs #16066. Refs #16256. Refs #16288. Related draft #15730 adds
optional reference selection to individual skill packages. This fix
applies automatic repository fallback and does not add that selection
UI.
**What happened?**
A project source showed 86 warnings. It rejected 23 skills solely
because references were absent from the isolated package. It also
treated web routes and inline Markdown examples as files. For
test-audit, repository scripts were resolved inside the skill folder.
**Expected behavior**
Retain referenced files that fit the package limits. Missing references
must not block an otherwise valid selected skill. Preserve content
validation and installed shared files.
**Steps to reproduce**
Import paperclipai/paperclip at commit
09a2f0b7b0 as a repository source. Select
test-audit. Inspect its references and saved files. Repeat with a skill
whose optional reference is missing.
## What Changed
- Add a bounded fallback that keeps skill folders and transitive
Markdown references with their original repository paths.
- Resolve existing repository-root resource paths. Ignore site-relative
web links and inline Markdown examples.
- Keep missing references advisory, including explicit imports and
automatic project imports.
- Share fallback with file previews. Reinspect cached dependency
failures at an unchanged upstream commit.
- Retain existing versions when fallback cannot preserve installed
shared files. Keep file limits, content audits, authorization and work
budgets.
- Update product contracts and Skills maps. No schema or public API
changes.
## Verification
- Red/green: three original regression cases failed before the fix and
passed afterward. Two review controls also reproduced omitted directory
siblings and duplicate blob reads before their fixes.
- Focused scanner, repository package, persistence, project
synchronization and GitHub access tests: 126 cases passed across local
and isolated Linux runs.
- Full recursive typecheck and `pnpm build` passed locally on
`555bd3fc90314dbf23ed0ffe7034429946c1a471`. The [full Paperclip CI
workflow](https://github.com/paperclipai/paperclip/actions/runs/38596749890)
passed on that head, including all general, serialized, Runner and eight
browser test shards. The duplicate local `pnpm test:run` was stopped
after CI completed (exit 143); it is not claimed as a completed local
full-suite pass.
- Real GitHub scan at the pinned public commit: 77 skills, 454 retained
files, 9,117,635 bytes. test-audit has no missing references. The full
source reports 23 warnings, including remaining file validation and
genuine missing-reference notices.
- Local browser: scanned the public repository, selected test-audit and
create-issue-interaction-ui, and imported both. The second skill
retained an advisory missing-reference warning. Both remained installed
after reload. The saved package exposes `scripts/run-vitest-stable.mjs`
(25,813 bytes) and `scripts/general-server-shard.mjs` (2,813 bytes). No
GitHub responses were mocked. No model execution was needed for this
import fix.
- Map checks and Git whitespace checks passed. Greptile is 5/5 on the
current head with both review findings resolved. The external Superagent
security scan concluded neutral/inconclusive after its agent exceeded
the prompt deadline. A check-run retry request returned HTTP 404. All
Paperclip CI gates passed, but merge is held pending a conclusive
security scan; this is not an all-checks-green claim.
## Risks
- Dependency detection covers explicit Markdown links and resource
paths. It does not infer all script imports or runtime dependencies.
- Referenced content can exceed package limits. The existing bounds
still apply, and warnings disclose omissions.
- Content validation still rejects invalid entrypoints and omits
rejected support files. This change does not make every upstream skill
importable.
- No migration is required. Existing sources with the old dependency
error are inspected again on refresh.
## Model Used
OpenAI Codex, GPT-6 family. The runtime did not expose the exact serving
model ID or context window. Used reasoning, code editing, terminal
execution and browser tools. 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
- [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.6 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.
Repository import, preview, and refresh share the bounded dependency-package fallback. Missing-reference warnings do not deny an otherwise authorized import. Recovered files come only from the same immutable, authorized Git tree and pass the existing content audit; no host paths or additional credentials are consulted. Source tests cover transitive files, limits, retained versions, and legacy dependency-error recovery.
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.