Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-06 05:56:19 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
9fb06afbfab284f8dcecf6ebc3dee3bfcda4e09d
PaperClipAI/maps/agent-access-map/skills.md
T
DottaandPaperclip dc9f387edc fix(api): surface existing skill source import in discovery (#18757) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents discover supported API operations through the public OpenAPI
catalog.
> - Importing existing skill content must retain its source provenance.
> - A normal source-import query misses the applicable operation on its
first page because that operation has little search metadata.
> - This pull request describes the existing import operation and its
source boundaries.
> - The benefit is clearer discovery without changing search scoring or
import authority.

## Linked Issues or Issue Description

**What happened?**

`search_api` does not return `POST
/api/companies/{companyId}/skills/import` in the first ten results for
`import skill from source SKILL.md`. Source-management operations rank
ahead of the import operation. The import entry has only the summary
“Import a skill.”

**Expected behavior**

Ordinary source-import discovery should surface the existing operation.
Its documentation should explain that imported content retains
provenance and remains subject to company policy and source checks.

**Steps to reproduce**

Call `searchRunnerApi({ query: "import skill from source SKILL.md",
limit: 10 })`. Inspect the operation IDs on the first page. The new
regression sends this result through the real bounded MCP serializer.

Related: #18717 clarifies the separate `create_skill` tool. This change
covers the existing source-import HTTP operation. Neither PR is merged
by this work.

## What Changed

- Expand only the source-import OpenAPI summary and description.
Describe allowed local skill directories, supported remote sources,
retained provenance and existing access checks.
- Add a first-page discovery regression through the actual authenticated
MCP bridge and serializer. Keep non-import lookup, company/mode refusal
and denial forwarding controls.
- Update the feature and access maps with the test scope and its limits.

## Verification

- Parent regression: the controlled loopback MCP response lacked the
applicable import operation on the first page.
- Focused current checks: 2,060 tests pass in
`skill-import-discovery.test.ts` and the existing `runner-api.test.ts`
owner.
- `node scripts/check-maps.mjs` passes. This checks map structure only.
- The first head had one server test job cancelled after a runner
shutdown signal. The reason for the shutdown is unknown. The reviewed
successor removes only two test comments required by contribution rules;
its four focused controls pass. The remaining obsolete CI run was
cancelled after that successor was published. No same-head retry was
used.
- The new test is under `server/src/__tests__`, which the production
server typecheck excludes and the server Vitest suite includes.
- No local app, database, native agent or provider model was run. Normal
PR CI on `a4aaae8e320fb1d56cdbff9f376ec832a634a5da` passed with 48
successful jobs and one skipped job, including the required `ci /
verify` and `ci / e2e` checks. No completed agent-import journey or
reliability result is claimed.
- Greptile is 5/5 on the current head with no unresolved threads. The
optional Paperclip Review check remains queued. This is not merge
authorization.
- Keep this core PR open and unmerged. Do not enable auto-merge.

## Risks

The expanded metadata can change where this operation ranks for related
queries. Search weights, request schemas, HTTP routes, source parsing,
authorization and company skill policy are unchanged. The synthetic 403
control proves denial forwarding; it does not qualify the real policy or
source-import route. A live import still needs separate acceptance.

## Model Used

OpenAI `gpt-6.1-sol`, through Codex with reasoning, source review and
code execution tools. The exact context-window size is not exposed by
this environment. A separate agent reviewed the source and contract
before publication.

## 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-11-03 06:29:13 -06:00

298 lines
15 KiB
Markdown
Raw Blame History

# Skill discovery, authoring, and policy — agent access
Product map: [Skill discovery, authoring, and policy](../feature-map/skills.md).
Feature ID: `skills`.
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.
Cold Git package recovery rechecks the original source's current setup identity,
company membership, policy and repository grant. It never borrows another company's
credentials or substitutes a moving branch for the saved commit. A missing/revoked
source fails with a reconnect error and persisted retry backoff. Warm access still
uses the ordinary skill/project permission check.
External package storage changes persistence, not agent authority. Runtime selection
still checks current company/project access before consulting immutable package caches;
no storage key is exposed as an agent capability. Public selected rows are constrained
to `access_source_id IS NULL` at their final read. Warm package and native asset caches
hold file metadata, never authorization decisions. The
[concurrency regression](../../server/src/__tests__/company-skills-runtime-concurrency.test.ts)
covers separate actors and revoked project access; the
[package regression](../../server/src/__tests__/skill-package-store.test.ts) covers
company isolation and warm-cache behavior. This does not claim live agent qualification.
Managed ownership remains in the existing `workspace` policy category. Immutable
content references do not grant authority: publication rechecks policy and source
access, and delivery/recovery rechecks the company's skill visibility. File reads
and mutations return `versionId`; content requests may supply `expectedVersionId`
and receive `409` on a stale base. Existing idempotent agent receipt shapes remain.
Detached assignments do not release active/recovering execution pins. These are
source-reviewed contracts; the independent-process board fixture is not agent
credential or hosted Runner qualification.
## `discovery`
Capability ID: `skills/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. Queue
and HTTP/2 sandbox callbacks also admit company skill detail and file reads;
file paths travel in the existing `path` query parameter. Skill mutations stay
subject to the existing bridge restrictions.
Policy: Company skill policy by action/resource plus platform invariants; test execution
additionally requires task-assignment authority.
Native `search_api` describes source import separately from authoring. Existing
SKILL.md content may come from an allowed local skill directory or a supported
remote source. Local workspace/managed-root and remote source-access checks still
apply. Discovery metadata grants no import permission and does not assign skills.
The [discovery protocol regression](../../server/src/__tests__/skill-import-discovery.test.ts)
checks the actual first-page result and bounded MCP output. Its synthetic 403
control proves denial forwarding, not a live skill-policy decision.
Evidence: `source-only` —
[implementation](../../server/src/routes/company-skills.ts#L208) 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`
Capability ID: `skills/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](../../server/src/routes/company-skills.ts#L208) 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`
Version lists and current/test-run version summaries contain file names and kinds.
Use `GET /api/companies/{companyId}/skills/{skillId}/versions/{versionId}` for the
selected version's file contents. Authorization remains company/skill scoped; support
inspection reads only stored bytes for the requested version and does not recover Git.
Capability ID: `skills/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](../../server/src/routes/company-skills.ts#L208) 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.
Runtime disk-cache expiration does not delete version records or change access. Normal
execution rematerializes saved bytes after existing skill authorization; cleanup is an
internal company-scoped maintenance operation, with no new agent endpoint. Verify pinned
restoration and active-run protection with `server/src/__tests__/skill-version-cache.test.ts`
and the assembled heartbeat runtime-skill tests; live acceptance remains separate.
Native runs with an empty effective or saved selection do not read skill files
or wait for the company cache lock. Explicit references still require the existing
skill authorization. Selected skills and legacy operational skills retain cache
exclusion and immutable version pinning. This changes no agent endpoint or grant;
the [configuration tests](../../server/src/__tests__/heartbeat-execution-configuration.test.ts)
cover the held-lock boundary with real PostgreSQL.
Concurrent preparations share only in-flight inventory reconciliation. After
that work, each actor's visible skill rows are read again under the company cache
lock. Snapshot delivery and durable run pins complete before the lock is released.
No permission result is shared or kept between requests. The
[concurrency tests](../../server/src/__tests__/company-skills-runtime-concurrency.test.ts)
cover separate actors and project-access revocation; this adds no agent API.
## `policy`
Capability ID: `skills/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](../../server/src/routes/company-skills.ts#L208) 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.
The configuration-gated `GET /api/agents/{id}/skills` reads repository cache
locations without materializing versions or validating their support files.
Assignment mutations and run preparation retain their existing authorization.
The [database-backed cache tests](../../server/src/__tests__/skill-version-cache.test.ts)
cover latest/pinned reads and full validation during execution; they do not prove
live agent access.
Both skill-list and skill-sync responses preserve stored version pins rather than
returning a resolved runtime version as a pin. Latest remains unpinned across an
assignment round trip.
## `testing`
Capability ID: `skills/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](../../server/src/routes/company-skills.ts#L208) 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.
Studio's `skill_test` work mode is admitted through native Runner selection and
preserved in execution input. The admitted task-bound scope restricts REST and
native authorization, including after task-mode edits and recovery. Native tools
allow only the harness task and admitted skills. Task creation, company browsing,
connectors and assigned MCP tools are unavailable; native mutation receipts recheck
the scope before replay or effects.
Preparation reads the pinned version from the durable test row, replaces ordinary
assignments, and enforces current skill access. Required environment skills retain
their owner policy; a shadowed test pin fails explicitly. Recovery preserves the
admitted selection. Preconfigured Runner homes reject managed Studio delivery.
The [execution configuration regression](../../server/src/__tests__/heartbeat-execution-configuration.test.ts)
covers unassigned historical pins, Beta skills disabled, revoked access, recovery,
unchanged agent assignments, and assembled heartbeat dispatch.
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.
Plugin runtime synchronization uses the agent's current skill access and immutable
version resolver. A change to an installed skill invalidates its referencing
agents. Private-source access changes also request reconciliation. This is a
host-to-plugin hook, not a new agent-facing endpoint. See
[contract](../../doc/plugins/AGENT_RUNTIME_SYNC.md#skills) and
[database coverage](../../server/src/__tests__/agent-runtime-skills.test.ts).
Reference in new issue View Git Blame Copy Permalink