mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - A responsibility shows the skills of the agents doing its work. People cannot say which skills a responsibility needs. > - The maintainer chose to file skills under responsibilities like projects, tasks and routines. > - Agents also need to set a skill's catalog details without rewriting its SKILL.md. > - This pull request lets people and agents file, move and remove company skills under a responsibility, and adds `update_skill_details`. > - The benefit is that a responsibility lists the skills it needs, beside the skills its agents already hold. ## Linked Issues or Issue Description Refs #22253, #22261 and #22274; this pull request is stacked on them. **Subsystem affected** Database (`responsibility_links`), shared types and validators, server responsibility service and routes, Dashboard versions, native runner tools, and the responsibility page UI. **Problem or motivation** Skills under a responsibility are only computed from the agents doing its work. A person cannot record that "Hiring needs interviewing", and an agent cannot file a skill when it maps work for a person. **Proposed solution** Add a nullable `skill_id` to `responsibility_links` and allow it as the one target of a link. Show filed and computed skills together. Let the file, unfile, lookup and link routes and tools take skills. Keep filed skills in Dashboard versions so undo covers them. Add a small live tool for a skill's tagline and categories. **Alternatives considered** Keeping skills computed only, and giving the skill to the agent that runs the responsibility, was the other option. It was not chosen. Extending `update_skill` would change its scenario contract, whose mock needs `markdown`, so the details tool is separate. ## What Changed - Review fixes: the default responsibility view's Skills "+" adds an existing skill, removes a filed one, or opens an agent's skills page. A newest Dashboard version without a skill list is upgraded in place, so the first skill filed after it is undone. Undo files again, or removes, only skills the restoring person can see. A read scope without a skill condition sees no filed skill. `update_skill_details` with only `skillId` is a no-op, as its schema allows. - Migration `0499`: add `responsibility_links.skill_id` (FK to `company_skills`, on delete cascade). Widen the single-target check to four targets. Add a unique `(responsibility_id, skill_id)` index and a `skill_id` index. The migration is idempotent and online-compatible (NOT VALID then VALIDATE, and the indexes are built CONCURRENTLY). It is listed in `MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS`. - Shared: `ResponsibilityLink.skillId`; `ResponsibilitySkillSummary.linkId` and `computed`; `skillId` in the link and lookup schemas; `skill` in `RESPONSIBILITY_FILE_ITEM_KINDS`; optional `skillIds` in Dashboard snapshot links. - Server: filing checks the reader's skill visibility (`skillAccessService`). The detail merges filed and computed skills into one card each. Lookup accepts `skillId`. Dashboard capture, restore and summary include filed skills. A version without `skillIds` leaves filed skills as they are when it is restored. - Tools: `file_under_responsibility`, `remove_from_responsibility` and `find_responsibilities_for` accept `kind: "skill"`. `get_responsibility` returns `linkId` and `computed` for each skill. Add `update_skill_details` (tagline and categories). - UI: the responsibility page has "Add existing skill". A filed skill shows "Filed here" and a remove button. Computed skills keep their holders. ## Verification - Server: the `responsibilit*` tests (new: file, find, move and unfile a skill; one card for a skill that is both filed and computed; undo of a filed skill from the Dashboard history), `skill-tools.test.ts` (new `update_skill_details` cases), `responsibility-tools`, `routine-tools`, `routines-routes`, `paperclip-runner-tool-authority`, `runner-api` and `openapi-routes`: 24 files, 2723 tests passed. - UI: responsibility page and component tests (16 files, 158 tests, including a new filed-skill test) pass. `pnpm --filter @paperclipai/ui typecheck` passed. - `@paperclipai/db` `check:migrations` passes and reports the override. The snapshot drift test passes. `tsc` passes for `db`, `shared` and the server layers. - Runner: catalog and semantic-tool tests (317) pass. All generator checks pass. ## Risks - The migration changes a check constraint on `responsibility_links`. The replacement accepts every row that the old check accepted. It is swapped as NOT VALID and then validated. The previous release never sets `skill_id`. - Deleting a company skill removes its links (cascade). - Filed skills follow the reader's skill visibility. A skill the reader may not see is not listed. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
91 lines
6.3 KiB
TypeScript
91 lines
6.3 KiB
TypeScript
import { describe, expect, it, vi } from "vitest";
|
|
import { callCreateSkillTool, createSkillToolInput, callUpdateSkillDetailsTool, callUpdateSkillTool, updateSkillToolInput } from "./skill-tools.js";
|
|
|
|
const input = {
|
|
name: "release-review", description: "Review release notes.", idempotencyKey: "release-review-1",
|
|
markdown: "---\nname: release-review\ndescription: Review release notes.\n---\n\n# Review\nCheck each release note against the change.\n",
|
|
};
|
|
|
|
describe("create skill tool", () => {
|
|
it("requires a usable skill with matching frontmatter", () => {
|
|
expect(createSkillToolInput.parse(input)).toEqual(input);
|
|
for (const markdown of ["I created it", "---\nname: different\ndescription: Review release notes.\n---\nBody", "---\nname: release-review\ndescription: Review release notes.\n---\n"]) {
|
|
expect(createSkillToolInput.safeParse({ ...input, markdown }).success).toBe(false);
|
|
}
|
|
expect(createSkillToolInput.safeParse({ ...input, companyId: "foreign" }).success).toBe(false);
|
|
});
|
|
|
|
it.each([
|
|
{ markdown: "---\nname: [broken\n---\nBody" },
|
|
{ markdown: input.markdown.replace("description: Review release notes.", "description: Different purpose.") },
|
|
{ slug: "another-skill" },
|
|
{ markdown: "No frontmatter." },
|
|
])("rejects invalid skill content before any API call (%j)", async (invalid) => {
|
|
const fetcher = vi.fn();
|
|
await expect(callCreateSkillTool({ arguments: { ...input, ...invalid },
|
|
apiUrl: "http://localhost:3100", token: "test-token", companyId: "company-1" }, fetcher)).rejects.toThrow();
|
|
expect(fetcher).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("uses authenticated company route and returns only a portable skill reference", async () => {
|
|
const fetcher = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: "skill-1", name: input.name,
|
|
slug: input.name, description: input.description, currentVersionId: "version-1", sourceLocator: "/private/managed/skill", markdown: input.markdown }), { status: 201 }));
|
|
const result = await callCreateSkillTool({ arguments: input, apiUrl: "http://localhost:3100/api", token: "test-token", companyId: "company-1" }, fetcher);
|
|
expect(fetcher).toHaveBeenCalledWith("http://localhost:3100/api/companies/company-1/skills", expect.objectContaining({ method: "POST" }));
|
|
expect(JSON.parse(fetcher.mock.calls[0]![1].body)).toEqual(input);
|
|
expect(result).toEqual({ id: "skill-1", name: input.name, slug: input.name, description: input.description, versionId: "version-1", studioPath: "/skills/studio/skill-1" });
|
|
});
|
|
});
|
|
|
|
describe("update skill tool", () => {
|
|
const args = { skillId: "00000000-0000-4000-8000-000000000001", expectedVersionId: "00000000-0000-4000-8000-000000000002",
|
|
markdown: input.markdown, idempotencyKey: "update-1" };
|
|
|
|
it("rejects incomplete content and untrusted scope without a request", async () => {
|
|
const fetcher = vi.fn();
|
|
expect(updateSkillToolInput.parse(args)).toEqual(args);
|
|
for (const invalid of [{ markdown: "# Missing frontmatter" }, { markdown: input.markdown.replace("# Review\nCheck each release note against the change.", " ") },
|
|
{ companyId: "other" }, { expectedVersionId: "not-a-uuid" }]) {
|
|
await expect(callUpdateSkillTool({ arguments: { ...args, ...invalid }, apiUrl: "http://localhost", token: "token", companyId: "company" }, fetcher)).rejects.toThrow();
|
|
}
|
|
expect(fetcher).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("calls the company file endpoint and returns a compact receipt", async () => {
|
|
const receipt = { skillId: args.skillId, versionId: "next-version", path: "SKILL.md", studioPath: `/skills/studio/${args.skillId}` };
|
|
const fetcher = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ...receipt, content: args.markdown }), { status: 200 }));
|
|
expect(await callUpdateSkillTool({ arguments: args, apiUrl: "http://localhost/api", token: "token", companyId: "company" }, fetcher)).toEqual(receipt);
|
|
expect(fetcher).toHaveBeenCalledWith(`http://localhost/api/companies/company/skills/${args.skillId}/files`, expect.objectContaining({ method: "PATCH" }));
|
|
expect(JSON.parse(fetcher.mock.calls[0]![1].body)).toEqual({ path: "SKILL.md", content: args.markdown,
|
|
expectedVersionId: args.expectedVersionId, idempotencyKey: args.idempotencyKey });
|
|
fetcher.mockResolvedValueOnce(new Response(JSON.stringify({ error: "Skill version changed" }), { status: 409 }));
|
|
await expect(callUpdateSkillTool({ arguments: args, apiUrl: "http://localhost", token: "token", companyId: "company" }, fetcher)).rejects.toThrow("Skill version changed");
|
|
});
|
|
});
|
|
|
|
describe("update skill details tool", () => {
|
|
const skillId = "00000000-0000-4000-8000-000000000001";
|
|
|
|
it("changes only the tagline and categories through the skill update API", async () => {
|
|
const fetcher = vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
|
|
id: skillId, name: "review", slug: "review", tagline: "Reviews pull requests", categories: ["engineering"],
|
|
}), { status: 200 }));
|
|
const result = await callUpdateSkillDetailsTool({ arguments: { skillId, tagline: "Reviews pull requests", categories: ["engineering"] },
|
|
apiUrl: "http://localhost/api", token: "token", companyId: "company" }, fetcher);
|
|
const [url, init] = fetcher.mock.calls[0]!;
|
|
expect(url).toBe(`http://localhost/api/companies/company/skills/${skillId}`);
|
|
expect(init?.method).toBe("PATCH");
|
|
expect(JSON.parse(String(init?.body))).toEqual({ tagline: "Reviews pull requests", categories: ["engineering"] });
|
|
expect(result).toEqual({ id: skillId, name: "review", slug: "review", tagline: "Reviews pull requests", categories: ["engineering"], studioPath: `/skills/studio/${skillId}` });
|
|
});
|
|
|
|
it("changes nothing without a detail, and refuses fields that live in SKILL.md", async () => {
|
|
const fetcher = vi.fn<typeof fetch>();
|
|
// The advertised schema requires only skillId, so that call is a no-op, not an error.
|
|
await expect(callUpdateSkillDetailsTool({ arguments: { skillId }, apiUrl: "http://localhost", token: "token", companyId: "company" }, fetcher))
|
|
.resolves.toEqual({ id: skillId, changed: false, note: expect.stringContaining("send tagline, categories or both") });
|
|
await expect(callUpdateSkillDetailsTool({ arguments: { skillId, name: "renamed" }, apiUrl: "http://localhost", token: "token", companyId: "company" }, fetcher)).rejects.toThrow();
|
|
expect(fetcher).not.toHaveBeenCalled();
|
|
});
|
|
});
|