mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-16 05:17:41 +02:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents and board users operate inside a company-scoped control plane where permissions decide which mutating actions they can perform > - Company skills are part of the reusable agent-company setup surface, but skill mutation had been coupled to broader agent-creation authority > - That coupling meant importing or managing skills required a permission that also implies hiring power, which is broader than the operation needs > - Paperclip already has a grant-based permission vocabulary, so skill mutation should be authorized through a dedicated `skills:create` capability while preserving existing default behavior for trusted agents > - This pull request adds the skill creation permission contract, enforces it on company skill mutations, exposes it in agent permission management, and documents the changed CLI/API expectations > - The benefit is a narrower, auditable permission path for skill import/create/update/delete flows without forcing agents to receive broader agent-creation authority ## Linked Issues or Issue Description No public issue is linked. Problem: company skill mutation APIs were effectively tied to broader agent creation authority. This PR splits skill mutation authorization onto the public `skills:create` permission while keeping existing default skill creation behavior for agents unless explicitly disabled. Related public PR found during duplicate search: #5330. That PR uses an older `canManageSkills` shape; this PR implements the `skills:create` grant path instead. ## What Changed - Added `skills:create` to shared permission constants and agent permission types/validators as `canCreateSkills`. - Backfilled default human/member role grants for `skills:create`. - Updated company skill mutation routes to require board/user or agent access to `skills:create`, while preserving legacy/default agent behavior through `canCreateSkills` unless explicitly disabled. - Updated agent permission update handling, UI permission controls, duplicate-agent payloads, plugin SDK fixtures, and agent detail API surfaces for `canCreateSkills`. - Added regression coverage for skill route authorization, permission schema/default behavior, invite grants, omitted permission updates, and duplicate-agent payloads. - Updated CLI and Paperclip skill documentation for the new skill creation permission. ## Verification - `pnpm exec vitest run server/src/__tests__/agent-permissions-service.test.ts server/src/__tests__/agent-permissions-routes.test.ts server/src/__tests__/company-skills-routes.test.ts server/src/__tests__/invite-join-grants.test.ts ui/src/lib/duplicate-agent-payload.test.ts` — 5 files, 90 tests passed. - `pnpm --filter @paperclipai/shared typecheck && pnpm --filter @paperclipai/server typecheck && pnpm --filter @paperclipai/ui typecheck` — passed. - `pnpm test:run ...changed files...` was attempted first, but the stable wrapper rejects explicit file arguments; direct Vitest was used for the same targeted files. ## Risks - Moderate authorization risk: this changes the gate for company skill mutations, so the tests cover board grant checks, agent explicit grant checks, legacy default allowance, and explicit denial. - Migration/backfill risk is low: the migration only grants `skills:create` to existing human roles that already need broad management capability. - UI/API compatibility risk is low: `canCreateSkills` remains default-on for full agent permissions, and the update validator preserves omitted values so unrelated permission edits do not re-enable disabled skill creation. > 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, GPT-5 coding agent with terminal/tool use enabled. ## 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>
80 lines
2.2 KiB
TypeScript
80 lines
2.2 KiB
TypeScript
import type { AgentDetail } from "@paperclipai/shared";
|
|
|
|
const INSTRUCTION_CONFIG_KEYS = [
|
|
"instructionsBundleMode",
|
|
"instructionsRootPath",
|
|
"instructionsEntryFile",
|
|
"instructionsFilePath",
|
|
"agentsMdPath",
|
|
"promptTemplate",
|
|
"bootstrapPromptTemplate",
|
|
] as const;
|
|
|
|
export type DuplicateInstructionsBundle = {
|
|
entryFile: string;
|
|
files: Record<string, string>;
|
|
};
|
|
|
|
type DuplicateAgentSource = Pick<
|
|
AgentDetail,
|
|
| "name"
|
|
| "role"
|
|
| "title"
|
|
| "icon"
|
|
| "reportsTo"
|
|
| "capabilities"
|
|
| "adapterType"
|
|
| "adapterConfig"
|
|
| "runtimeConfig"
|
|
| "defaultEnvironmentId"
|
|
| "budgetMonthlyCents"
|
|
| "permissions"
|
|
| "metadata"
|
|
>;
|
|
|
|
function cloneRecord(value: Record<string, unknown> | null | undefined): Record<string, unknown> {
|
|
if (!value) return {};
|
|
return JSON.parse(JSON.stringify(value)) as Record<string, unknown>;
|
|
}
|
|
|
|
export function duplicateAgentName(name: string): string {
|
|
const trimmed = name.trim();
|
|
return `${trimmed || "Agent"} Copy`;
|
|
}
|
|
|
|
export function buildDuplicateAgentPayload(
|
|
agent: DuplicateAgentSource,
|
|
instructionsBundle?: DuplicateInstructionsBundle | null,
|
|
): Record<string, unknown> {
|
|
const adapterConfig = cloneRecord(agent.adapterConfig);
|
|
for (const key of INSTRUCTION_CONFIG_KEYS) {
|
|
delete adapterConfig[key];
|
|
}
|
|
|
|
const payload: Record<string, unknown> = {
|
|
name: duplicateAgentName(agent.name),
|
|
role: agent.role,
|
|
adapterType: agent.adapterType,
|
|
adapterConfig,
|
|
runtimeConfig: cloneRecord(agent.runtimeConfig),
|
|
defaultEnvironmentId: agent.defaultEnvironmentId ?? null,
|
|
budgetMonthlyCents: agent.budgetMonthlyCents ?? 0,
|
|
permissions: {
|
|
canCreateAgents: Boolean(agent.permissions?.canCreateAgents),
|
|
canCreateSkills: agent.permissions?.canCreateSkills !== false,
|
|
},
|
|
};
|
|
|
|
if (agent.title) payload.title = agent.title;
|
|
if (agent.icon) payload.icon = agent.icon;
|
|
if (agent.reportsTo) payload.reportsTo = agent.reportsTo;
|
|
if (agent.capabilities) payload.capabilities = agent.capabilities;
|
|
if (agent.metadata) payload.metadata = cloneRecord(agent.metadata);
|
|
|
|
if (instructionsBundle && Object.keys(instructionsBundle.files).length > 0) {
|
|
payload.instructionsBundle = instructionsBundle;
|
|
}
|
|
|
|
return payload;
|
|
}
|