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>
280 lines
12 KiB
TypeScript
280 lines
12 KiB
TypeScript
import { z } from "zod";
|
|
import {
|
|
RESPONSIBILITY_AREA_SOURCES,
|
|
RESPONSIBILITY_AREA_STATUSES,
|
|
RESPONSIBILITY_DELEGATION_MODES,
|
|
RESPONSIBILITY_HEALTH_OVERRIDES,
|
|
RESPONSIBILITY_METRIC_DIRECTIONS,
|
|
RESPONSIBILITY_SOURCES,
|
|
RESPONSIBILITY_STATUSES,
|
|
} from "../constants.js";
|
|
import {
|
|
RESPONSIBILITY_METRIC_KINDS,
|
|
resolveResponsibilityMetricKind,
|
|
responsibilityBarIssues,
|
|
responsibilityMetricNameSchema,
|
|
responsibilityMetricReadingSchema,
|
|
responsibilityMetricUnitSchema,
|
|
responsibilityMetricValueSchema,
|
|
} from "../responsibility-bars.js";
|
|
|
|
const title = z.string().trim().min(1).max(200);
|
|
const longText = z.string().trim().max(10_000);
|
|
const optionalText = longText.optional().nullable();
|
|
const requiredText = longText.min(1);
|
|
const metricName = responsibilityMetricNameSchema;
|
|
const metricUnit = responsibilityMetricUnitSchema;
|
|
const metricValue = responsibilityMetricValueSchema;
|
|
const sortOrder = z.number().int().min(-1_000_000).max(1_000_000);
|
|
|
|
/** The inputs that set a metric on create: sending any one of them means the whole metric must be there. */
|
|
const CREATE_METRIC_KEYS = [
|
|
"metricKind",
|
|
"metricName",
|
|
"metricUnit",
|
|
"metricDirection",
|
|
"metricTarget",
|
|
"metricLow",
|
|
"metricHigh",
|
|
"metricCurrent",
|
|
] as const;
|
|
|
|
const createResponsibilityFields = z.object({
|
|
title,
|
|
description: optionalText,
|
|
/**
|
|
* The bar, as a sentence. A person may leave it out (with the metric) and
|
|
* set the bar later; it is required with a metric, and always from an agent.
|
|
*/
|
|
standard: optionalText,
|
|
/**
|
|
* The bar template. Omitted: `percentage` when metricUnit is "%", otherwise
|
|
* `volume`. Each template requires and allows its own fields (see
|
|
* `RESPONSIBILITY_BAR_TEMPLATES`).
|
|
*/
|
|
metricKind: z.enum(RESPONSIBILITY_METRIC_KINDS).optional(),
|
|
/** What is measured. A person may leave the whole metric out; required from an agent. */
|
|
metricName: metricName.optional(),
|
|
/** Volume and percentage (required for them). */
|
|
metricTarget: metricValue.optional().nullable(),
|
|
/** Range (required for it): the lowest value that is still inside. */
|
|
metricLow: metricValue.optional().nullable(),
|
|
/** Range (required for it): the highest value that is still inside. */
|
|
metricHigh: metricValue.optional().nullable(),
|
|
/** A number; true or false for `yes_no`. */
|
|
metricCurrent: responsibilityMetricReadingSchema.optional().nullable(),
|
|
metricUnit: metricUnit.optional().nullable(),
|
|
/** Volume and percentage only. Default `at_least`. */
|
|
metricDirection: z.enum(RESPONSIBILITY_METRIC_DIRECTIONS).optional(),
|
|
/** An area in the same company. */
|
|
areaId: z.string().uuid().optional().nullable(),
|
|
/**
|
|
* An area by title instead of `areaId`: the live area with that title (any
|
|
* case), or a new one made in the same transaction. Not with `areaId`.
|
|
*/
|
|
areaTitle: title.optional(),
|
|
/** An agent in the same company that runs the work. */
|
|
runByAgentId: z.string().uuid().optional().nullable(),
|
|
evidence: optionalText,
|
|
/** Board: defaults to the acting user. Agent: defaults to the person its run works for. */
|
|
ownerUserId: z.string().trim().min(1).optional(),
|
|
/** Board only; agents always create `proposed`. Board default: `active`. */
|
|
status: z.enum(RESPONSIBILITY_STATUSES).optional(),
|
|
/** Board only; agents always create `onboarding`. Board default: `manual`. */
|
|
source: z.enum(RESPONSIBILITY_SOURCES).optional(),
|
|
sortOrder: sortOrder.optional(),
|
|
});
|
|
|
|
type CreateResponsibilityFields = z.infer<typeof createResponsibilityFields>;
|
|
|
|
/** A metric that is sent must be whole: the sentence, what is measured, and the template's inputs. */
|
|
function refineCreateBar(value: CreateResponsibilityFields, ctx: z.RefinementCtx) {
|
|
const measured = CREATE_METRIC_KEYS.some((key) => value[key] !== undefined && value[key] !== null);
|
|
if (!measured) return;
|
|
if (!value.standard?.trim()) {
|
|
ctx.addIssue({ code: "custom", path: ["standard"], message: "A responsibility with a metric needs its bar as a sentence (standard)" });
|
|
}
|
|
if (!value.metricName?.trim()) {
|
|
ctx.addIssue({ code: "custom", path: ["metricName"], message: "A responsibility with a metric needs what is measured (metricName)" });
|
|
}
|
|
const metricKind = value.metricKind ?? resolveResponsibilityMetricKind(null, value.metricUnit);
|
|
for (const issue of responsibilityBarIssues({ ...value, metricKind }, { complete: true })) {
|
|
ctx.addIssue({ code: "custom", path: [issue.field], message: issue.message });
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Create a responsibility. A person may send only a title: it is saved with
|
|
* no bar and reads as not measured until its bar is set. Any metric input
|
|
* makes the whole bar required (the sentence, what is measured and the
|
|
* template's inputs), so a half-filled metric is refused. Agents send
|
|
* `proposeResponsibilitySchema` instead, which always requires the bar.
|
|
*/
|
|
export const createResponsibilitySchema = createResponsibilityFields.strict().superRefine(refineCreateBar);
|
|
|
|
export type CreateResponsibility = z.infer<typeof createResponsibilitySchema>;
|
|
|
|
/** What an agent sends to propose a responsibility: the create body, with the whole bar required. */
|
|
export const proposeResponsibilitySchema = createResponsibilityFields
|
|
.extend({ standard: requiredText, metricName })
|
|
.strict()
|
|
.superRefine(refineCreateBar);
|
|
|
|
export type ProposeResponsibility = z.infer<typeof proposeResponsibilitySchema>;
|
|
|
|
export const updateResponsibilitySchema = z.object({
|
|
title: title.optional(),
|
|
description: optionalText,
|
|
/** `null` clears it; refused on an active responsibility. */
|
|
standard: optionalText,
|
|
/** `null` clears it; refused on an active responsibility. */
|
|
metricName: metricName.optional().nullable(),
|
|
/**
|
|
* Change the bar template. Inputs the new template does not use are cleared,
|
|
* and so is the reading unless metricCurrent is sent too. The merged bar
|
|
* must follow the template's rules (422 otherwise).
|
|
*/
|
|
metricKind: z.enum(RESPONSIBILITY_METRIC_KINDS).optional(),
|
|
/** `null` clears it; refused on an active responsibility. */
|
|
metricTarget: metricValue.optional().nullable(),
|
|
/** Range: `null` clears it; refused on an active responsibility. */
|
|
metricLow: metricValue.optional().nullable(),
|
|
/** Range: `null` clears it; refused on an active responsibility. */
|
|
metricHigh: metricValue.optional().nullable(),
|
|
/**
|
|
* The latest reading; sets `metricUpdatedAt`. A number, or true/false for a
|
|
* `yes_no` bar. On an active responsibility an agent may send this field
|
|
* alone when it runs the responsibility or is assigned a task or routine
|
|
* under it.
|
|
*/
|
|
metricCurrent: responsibilityMetricReadingSchema.optional().nullable(),
|
|
metricUnit: metricUnit.optional().nullable(),
|
|
/** Volume and percentage only. */
|
|
metricDirection: z.enum(RESPONSIBILITY_METRIC_DIRECTIONS).optional().nullable(),
|
|
areaId: z.string().uuid().optional().nullable(),
|
|
/** Move it to the live area with this title (any case), made in the same transaction when there is none. Not with `areaId`. */
|
|
areaTitle: title.optional(),
|
|
runByAgentId: z.string().uuid().optional().nullable(),
|
|
evidence: optionalText,
|
|
sortOrder: sortOrder.optional(),
|
|
/** `null` clears the override. */
|
|
healthOverride: z.enum(RESPONSIBILITY_HEALTH_OVERRIDES).nullable().optional(),
|
|
healthNote: optionalText,
|
|
status: z.enum(RESPONSIBILITY_STATUSES).optional(),
|
|
}).strict();
|
|
|
|
export type UpdateResponsibility = z.infer<typeof updateResponsibilitySchema>;
|
|
|
|
export const linkResponsibilitySchema = z.object({
|
|
projectId: z.string().uuid().optional(),
|
|
issueId: z.string().uuid().optional(),
|
|
routineId: z.string().uuid().optional(),
|
|
/** A company skill in the same company. */
|
|
skillId: z.string().uuid().optional(),
|
|
}).strict().refine(
|
|
(value) => [value.projectId, value.issueId, value.routineId, value.skillId].filter((id) => id !== undefined).length === 1,
|
|
{ message: "Provide exactly one of projectId, issueId, routineId or skillId" },
|
|
);
|
|
|
|
export type LinkResponsibility = z.infer<typeof linkResponsibilitySchema>;
|
|
|
|
export const delegateResponsibilitySchema = z.object({
|
|
title,
|
|
instructions: longText.optional().nullable(),
|
|
assigneeAgentId: z.string().uuid(),
|
|
mode: z.enum(RESPONSIBILITY_DELEGATION_MODES),
|
|
projectId: z.string().uuid().optional().nullable(),
|
|
}).strict();
|
|
|
|
export type DelegateResponsibility = z.infer<typeof delegateResponsibilitySchema>;
|
|
|
|
const booleanQuery = z
|
|
.union([z.boolean(), z.enum(["true", "false", "1", "0"])])
|
|
.transform((value) => value === true || value === "true" || value === "1");
|
|
|
|
export const listResponsibilitiesQuerySchema = z.object({
|
|
/** Board: defaults to the acting user. Agent: defaults to the person its run works for. */
|
|
ownerUserId: z.string().trim().min(1).optional(),
|
|
includeLetGo: booleanQuery.optional().default(false),
|
|
});
|
|
|
|
export type ListResponsibilitiesQuery = z.infer<typeof listResponsibilitiesQuerySchema>;
|
|
|
|
export const createResponsibilityAreaSchema = z.object({
|
|
title,
|
|
description: optionalText,
|
|
sortOrder: sortOrder.optional(),
|
|
/** Board only; agents always create `proposed`. Board default: `active`. */
|
|
status: z.enum(["proposed", "active"]).optional(),
|
|
/** Board only; agents always create `onboarding`. Board default: `manual`. */
|
|
source: z.enum(RESPONSIBILITY_AREA_SOURCES).optional(),
|
|
}).strict();
|
|
|
|
export type CreateResponsibilityArea = z.infer<typeof createResponsibilityAreaSchema>;
|
|
|
|
export const updateResponsibilityAreaSchema = z.object({
|
|
title: title.optional(),
|
|
description: optionalText,
|
|
sortOrder: sortOrder.optional(),
|
|
status: z.enum(RESPONSIBILITY_AREA_STATUSES).optional(),
|
|
}).strict();
|
|
|
|
export type UpdateResponsibilityArea = z.infer<typeof updateResponsibilityAreaSchema>;
|
|
|
|
export const listResponsibilityAreasQuerySchema = z.object({
|
|
includeArchived: booleanQuery.optional().default(false),
|
|
});
|
|
|
|
export type ListResponsibilityAreasQuery = z.infer<typeof listResponsibilityAreasQuerySchema>;
|
|
|
|
export const responsibilityLinkLookupQuerySchema = z.object({
|
|
issueId: z.string().uuid().optional(),
|
|
projectId: z.string().uuid().optional(),
|
|
routineId: z.string().uuid().optional(),
|
|
skillId: z.string().uuid().optional(),
|
|
}).refine(
|
|
(value) => [value.projectId, value.issueId, value.routineId, value.skillId].filter((id) => id !== undefined).length === 1,
|
|
{ message: "Provide exactly one of issueId, projectId, routineId or skillId" },
|
|
);
|
|
|
|
export type ResponsibilityLinkLookupQuery = z.infer<typeof responsibilityLinkLookupQuerySchema>;
|
|
|
|
/** What can be filed under a responsibility by kind and id. */
|
|
export const RESPONSIBILITY_FILE_ITEM_KINDS = ["project", "task", "routine", "skill"] as const;
|
|
export type ResponsibilityFileItemKind = (typeof RESPONSIBILITY_FILE_ITEM_KINDS)[number];
|
|
|
|
const fileItem = z.object({
|
|
kind: z.enum(RESPONSIBILITY_FILE_ITEM_KINDS),
|
|
id: z.string().uuid(),
|
|
}).strict();
|
|
|
|
/**
|
|
* File items under a responsibility in one step. `moveFrom` makes it a move:
|
|
* the items are also unfiled from that responsibility, or with `all` from
|
|
* every other proposed or active responsibility of the same owner.
|
|
*/
|
|
export const fileResponsibilityItemsSchema = z.object({
|
|
items: z.array(fileItem).min(1).max(50),
|
|
moveFrom: z.union([z.string().uuid(), z.literal("all")]).optional(),
|
|
}).strict();
|
|
|
|
export type FileResponsibilityItems = z.infer<typeof fileResponsibilityItemsSchema>;
|
|
|
|
/** Unfile items from a responsibility by kind and id; no link ids needed. */
|
|
export const unfileResponsibilityItemsSchema = z.object({
|
|
items: z.array(fileItem).min(1).max(50),
|
|
}).strict();
|
|
|
|
export type UnfileResponsibilityItems = z.infer<typeof unfileResponsibilityItemsSchema>;
|
|
|
|
/** An agent deletes only with the id of the confirmation card the person accepted. */
|
|
export const deleteResponsibilityQuerySchema = z.object({
|
|
confirmationId: z.string().uuid().optional(),
|
|
});
|
|
|
|
export const deleteResponsibilityAreaQuerySchema = z.object({
|
|
confirmationId: z.string().uuid().optional(),
|
|
/** An area for the responsibilities under it; without one they are left with no area. */
|
|
moveResponsibilitiesTo: z.string().uuid().optional(),
|
|
});
|