mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +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>
630 lines
32 KiB
TypeScript
630 lines
32 KiB
TypeScript
import type {
|
|
Responsibility,
|
|
ResponsibilityDetail,
|
|
ResponsibilityLinkLookupEntry,
|
|
ResponsibilityOverview,
|
|
ResponsibilityOverviewArea,
|
|
ResponsibilityArea,
|
|
ResponsibilityStatusReportState,
|
|
ResponsibilityWithRollup,
|
|
} from "@paperclipai/shared";
|
|
import { z } from "zod";
|
|
import { HttpError } from "../errors.js";
|
|
import { fetchPaperclipApi } from "./paperclip-api-loopback.js";
|
|
import { RESPONSIBILITIES_DISABLED_CODE, RESPONSIBILITIES_OFF_GUIDANCE } from "./responsibilities-disabled.js";
|
|
|
|
/**
|
|
* Native agent tools for areas and responsibilities. Every call goes through
|
|
* the authenticated HTTP API with the run's agent token, so the routes'
|
|
* company, privacy and permission checks and their activity log apply
|
|
* unchanged. Results are compact projections an agent can read in one pass.
|
|
*/
|
|
export const RESPONSIBILITY_TOOL_NAMES = [
|
|
"list_responsibilities", "get_responsibility", "find_responsibilities_for",
|
|
"create_area", "update_area", "delete_area",
|
|
"create_responsibility", "update_responsibility", "delete_responsibility",
|
|
"file_under_responsibility", "remove_from_responsibility",
|
|
] as const;
|
|
export type ResponsibilityToolName = (typeof RESPONSIBILITY_TOOL_NAMES)[number];
|
|
|
|
export function isResponsibilityTool(name: string): name is ResponsibilityToolName {
|
|
return (RESPONSIBILITY_TOOL_NAMES as readonly string[]).includes(name);
|
|
}
|
|
|
|
/** What the agent says when the instance has the feature off; also used for the prompt note. */
|
|
export const RESPONSIBILITIES_TURNED_OFF_MESSAGE = RESPONSIBILITIES_OFF_GUIDANCE;
|
|
|
|
const uuid = z.string().guid();
|
|
|
|
export const listResponsibilitiesToolInput = z.object({
|
|
ownerUserId: z.string().trim().min(1).max(200).optional(),
|
|
areaId: uuid.optional(),
|
|
includeLetGo: z.boolean().optional().default(false),
|
|
includeProposed: z.boolean().optional().default(true),
|
|
includeArchivedAreas: z.boolean().optional().default(false),
|
|
}).strict();
|
|
|
|
export const getResponsibilityToolInput = z.object({ responsibilityId: uuid }).strict();
|
|
|
|
export const findResponsibilitiesForToolInput = z.object({
|
|
kind: z.enum(["project", "task", "routine", "skill"]),
|
|
/** A UUID; for a task, an identifier such as PAP-123 also works. */
|
|
id: z.string().trim().min(1).max(200),
|
|
}).strict();
|
|
|
|
/** The tool-facing denial while the instance has the feature off. */
|
|
export function responsibilityToolsDisabledError() {
|
|
return new HttpError(404, RESPONSIBILITIES_TURNED_OFF_MESSAGE, { code: RESPONSIBILITIES_DISABLED_CODE });
|
|
}
|
|
|
|
/** What a write reports beside its body: the Dashboard version it saved, if any, and whose Dashboard it is. */
|
|
type ApiMeta = { version?: string | null; owner?: string | null };
|
|
type ApiCall = (method: "GET" | "POST" | "PATCH" | "DELETE", path: string, body?: unknown, meta?: ApiMeta) => Promise<unknown>;
|
|
|
|
function apiCaller(input: { apiUrl: string; token: string }, fetcher: typeof fetch): ApiCall {
|
|
return async (method, path, body, meta) => {
|
|
const response = await fetchPaperclipApi({ ...input, method, path, body, fetcher });
|
|
const result = await response.json().catch(() => ({}));
|
|
if (meta && response.headers.get("x-paperclip-dashboard-version")) {
|
|
meta.version = response.headers.get("x-paperclip-dashboard-version");
|
|
meta.owner = response.headers.get("x-paperclip-dashboard-owner");
|
|
}
|
|
if (!response.ok) {
|
|
if (result?.code === RESPONSIBILITIES_DISABLED_CODE) {
|
|
throw responsibilityToolsDisabledError();
|
|
}
|
|
throw new HttpError(response.status, typeof result?.error === "string" ? result.error : `Responsibility tool failed (${response.status})`,
|
|
typeof result?.code === "string" ? { code: result.code } : undefined);
|
|
}
|
|
return result;
|
|
};
|
|
}
|
|
|
|
function bar(row: Responsibility) {
|
|
if (!row.metricName) return null;
|
|
return {
|
|
kind: row.metricKind,
|
|
name: row.metricName,
|
|
unit: row.metricUnit,
|
|
target: row.metricTarget,
|
|
low: row.metricLow,
|
|
high: row.metricHigh,
|
|
direction: row.metricDirection,
|
|
current: row.metricCurrent,
|
|
updatedAt: row.metricUpdatedAt,
|
|
};
|
|
}
|
|
|
|
function pageHref(prefix: string | null | undefined, path: string) {
|
|
return prefix ? `/${encodeURIComponent(prefix)}${path}` : null;
|
|
}
|
|
|
|
function summary(row: ResponsibilityWithRollup, prefix: string | null | undefined) {
|
|
return {
|
|
id: row.id,
|
|
title: row.title,
|
|
status: row.status,
|
|
areaId: row.areaId,
|
|
standard: row.standard,
|
|
bar: bar(row),
|
|
health: row.rollup.health,
|
|
healthOverridden: row.rollup.healthOverridden,
|
|
healthNote: row.healthNote,
|
|
statusSentence: row.rollup.statusSentence,
|
|
runByAgentId: row.runByAgentId,
|
|
counts: {
|
|
projects: row.rollup.projects,
|
|
routines: row.rollup.routines,
|
|
openTasks: row.rollup.openTasks,
|
|
blockedTasks: row.rollup.blockedTasks,
|
|
doneTasks: row.rollup.doneTasks,
|
|
},
|
|
...(row.status === "proposed" ? { evidence: row.evidence, proposedByAgentId: row.proposedByAgentId } : {}),
|
|
href: pageHref(prefix, `/responsibilities/${encodeURIComponent(row.id)}`),
|
|
};
|
|
}
|
|
|
|
type AreaEntry = Pick<ResponsibilityArea, "id" | "title" | "description" | "status">;
|
|
|
|
async function listResponsibilities(call: ApiCall, companyId: string, args: unknown, prefix: string | null | undefined) {
|
|
const input = listResponsibilitiesToolInput.parse(args);
|
|
const query = new URLSearchParams({ includeLetGo: String(input.includeLetGo) });
|
|
if (input.ownerUserId) query.set("ownerUserId", input.ownerUserId);
|
|
const company = encodeURIComponent(companyId);
|
|
const [overview, archivedAreas] = await Promise.all([
|
|
call("GET", `/companies/${company}/responsibilities?${query}`) as Promise<ResponsibilityOverview>,
|
|
input.includeArchivedAreas
|
|
? call("GET", `/companies/${company}/responsibility-areas?includeArchived=true`) as Promise<ResponsibilityArea[]>
|
|
: Promise.resolve([] as ResponsibilityArea[]),
|
|
]);
|
|
const rows = [...overview.responsibilities, ...(input.includeProposed ? overview.proposed : [])];
|
|
const areas = new Map<string, AreaEntry>();
|
|
for (const area of [...overview.areas, ...archivedAreas] as Array<ResponsibilityOverviewArea | ResponsibilityArea>) {
|
|
// Archived areas only on request; responsibilities in one then list under withoutArea.
|
|
if (area.status === "archived" && !input.includeArchivedAreas) continue;
|
|
if (!areas.has(area.id)) areas.set(area.id, { id: area.id, title: area.title, description: area.description, status: area.status });
|
|
}
|
|
const inArea = (areaId: string | null) => rows.filter((row) => row.areaId === areaId).map((row) => summary(row, prefix));
|
|
const areaList = [...areas.values()]
|
|
.filter((area) => !input.areaId || area.id === input.areaId)
|
|
.map((area) => ({ ...area, responsibilities: inArea(area.id) }));
|
|
const loose = overview.loose;
|
|
const scoped = input.areaId ? rows.filter((row) => row.areaId === input.areaId) : rows;
|
|
const count = (status: string) => scoped.filter((row) => row.status === status).length;
|
|
const activeByHealth = { behind: 0, at_risk: 0, on_track: 0, not_measured: 0 };
|
|
for (const row of scoped) if (row.status === "active") activeByHealth[row.rollup.health] += 1;
|
|
return {
|
|
ownerUserId: overview.ownerUserId,
|
|
areas: areaList,
|
|
...(input.areaId ? {} : { withoutArea: rows.filter((row) => !row.areaId || !areas.has(row.areaId)).map((row) => summary(row, prefix)) }),
|
|
// With areaId, totals count only that area; the person's task and project totals and the company's uncovered work are left out.
|
|
totals: input.areaId
|
|
? { scope: "area", active: count("active"), proposed: count("proposed"), letGo: count("let_go"), activeByHealth }
|
|
: {
|
|
scope: "person",
|
|
active: count("active"),
|
|
proposed: count("proposed"),
|
|
letGo: count("let_go"),
|
|
activeByHealth,
|
|
openTasks: overview.totals.openTasks,
|
|
blockedTasks: overview.totals.blockedTasks,
|
|
projects: overview.totals.projects,
|
|
lateProjects: overview.totals.lateProjects,
|
|
},
|
|
...(input.areaId ? {} : {
|
|
uncoveredWork: {
|
|
note: "Company work filed under no proposed or active responsibility of anyone, directly or through its project. Counts are complete; lists are capped.",
|
|
routineCount: loose.routineCount,
|
|
projectCount: loose.projectCount,
|
|
openTaskCount: loose.openTaskCount,
|
|
routines: loose.routines.map((routine) => ({ id: routine.id, title: routine.title, status: routine.status, assigneeAgentId: routine.assigneeAgentId, projectId: routine.projectId })),
|
|
projects: loose.projects.map((project) => ({ id: project.id, name: project.name, status: project.status, targetDate: project.targetDate, leadAgentId: project.leadAgentId })),
|
|
tasks: loose.tasks.map((task) => ({ id: task.id, identifier: task.identifier, title: task.title, status: task.status, assigneeAgentId: task.assigneeAgentId, assigneeUserId: task.assigneeUserId, projectId: task.projectId })),
|
|
},
|
|
}),
|
|
...(overview.responsibilities.length + overview.proposed.length === 0 ? {
|
|
guidance: "This person has no responsibilities yet. Ask what they are responsible for before proposing any; do not invent them.",
|
|
} : rows.length === 0 ? {
|
|
guidance: `This person has ${overview.proposed.length} proposed responsibilities, hidden by includeProposed: false. Read them before proposing more.`,
|
|
} : {}),
|
|
};
|
|
}
|
|
|
|
async function getResponsibility(call: ApiCall, args: unknown, prefix: string | null | undefined) {
|
|
const { responsibilityId } = getResponsibilityToolInput.parse(args);
|
|
const id = encodeURIComponent(responsibilityId);
|
|
const [detail, report] = await Promise.all([
|
|
call("GET", `/responsibilities/${id}`) as Promise<ResponsibilityDetail>,
|
|
// The report is supporting context: the detail alone still answers the call.
|
|
(call("GET", `/responsibilities/${id}/status-report`) as Promise<ResponsibilityStatusReportState>).catch(() => null),
|
|
]);
|
|
return {
|
|
...summary(detail, prefix),
|
|
ownerUserId: detail.ownerUserId,
|
|
description: detail.description,
|
|
evidence: detail.evidence,
|
|
area: detail.area,
|
|
workSummary: detail.rollup.workSummary.map((signal) => signal.text),
|
|
nextDueAt: detail.rollup.nextDueAt,
|
|
projects: detail.projects.map((project) => ({
|
|
linkId: project.linkId, id: project.id, name: project.name, status: project.status,
|
|
targetDate: project.targetDate, leadAgentId: project.leadAgentId, progress: project.progress,
|
|
})),
|
|
tasks: detail.tasks.map((task) => ({
|
|
linkId: task.linkId, membership: task.membership, id: task.id, identifier: task.identifier, title: task.title,
|
|
status: task.status, assigneeAgentId: task.assigneeAgentId, assigneeUserId: task.assigneeUserId, projectId: task.projectId,
|
|
})),
|
|
tasksTruncated: detail.tasksTruncated,
|
|
routines: detail.routines.map((routine) => ({
|
|
linkId: routine.linkId, membership: routine.membership, id: routine.id, title: routine.title, status: routine.status,
|
|
assigneeAgentId: routine.assigneeAgentId, projectId: routine.projectId, lastRun: routine.lastRun,
|
|
})),
|
|
skills: detail.skills.map((skill) => ({
|
|
id: skill.id, key: skill.key, name: skill.name, linkId: skill.linkId, computed: skill.computed, agentIds: skill.agentIds,
|
|
})),
|
|
artifactsTotal: detail.artifactsTotal,
|
|
statusReport: report ? { current: report.current, reporterAgentId: report.reporterAgentId, updateRequested: report.updateRequested } : null,
|
|
membershipNote: "membership direct means the item is filed under it (linkId set); project means it is under it through a filed project. A skill with linkId is filed here; computed means an agent doing the work holds it.",
|
|
};
|
|
}
|
|
|
|
async function findResponsibilitiesFor(call: ApiCall, companyId: string, args: unknown, prefix: string | null | undefined) {
|
|
const input = findResponsibilitiesForToolInput.parse(args);
|
|
let id = input.id;
|
|
let identifier: string | null = null;
|
|
if (input.kind === "task") {
|
|
// The issue route accepts an identifier and applies the same read rules.
|
|
const issue = await call("GET", `/issues/${encodeURIComponent(input.id)}`) as { id: string; identifier: string | null };
|
|
id = issue.id;
|
|
identifier = issue.identifier;
|
|
} else if (!uuid.safeParse(id).success) {
|
|
throw new HttpError(422, `A ${input.kind} id must be a UUID`);
|
|
}
|
|
const param = input.kind === "task" ? "issueId" : `${input.kind}Id`;
|
|
const result = await call("GET", `/companies/${encodeURIComponent(companyId)}/responsibility-links/lookup?${new URLSearchParams({ [param]: id })}`) as {
|
|
responsibilities: ResponsibilityLinkLookupEntry[];
|
|
};
|
|
return {
|
|
item: { kind: input.kind, id, ...(identifier ? { identifier } : {}) },
|
|
responsibilities: result.responsibilities.map((entry) => ({
|
|
...entry,
|
|
href: pageHref(prefix, `/responsibilities/${encodeURIComponent(entry.id)}`),
|
|
})),
|
|
...(result.responsibilities.length === 0 ? { note: "Filed under no proposed or active responsibility." } : {}),
|
|
};
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Changes. The routes decide what an agent may do: acting for the person its
|
|
// run works for, it may do what that person could, and each change is saved
|
|
// as a Dashboard version that person can undo. Otherwise it may only propose.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
const UNDO_NOTE = "Saved as a version in the Dashboard history of the person in dashboardOwnerUserId, where they can undo it.";
|
|
const NOT_IN_HISTORY_NOTE = "This change cannot be undone from the person's Dashboard history: it holds only active responsibilities and their areas, and Undo never renames, re-describes, reorders or un-archives an area other people's responsibilities share. To reverse it, change it back.";
|
|
const BAR_NOTE = "Undo from the Dashboard history does not put an old bar or metric back; the earlier readings stay in the metric's history.";
|
|
|
|
function undoNote(meta: ApiMeta) {
|
|
return meta.version
|
|
? { undo: UNDO_NOTE, dashboardVersionId: meta.version, dashboardOwnerUserId: meta.owner ?? null }
|
|
: { undo: NOT_IN_HISTORY_NOTE };
|
|
}
|
|
const itemKind = z.enum(["project", "task", "routine", "skill"]);
|
|
const toolItem = z.object({ kind: itemKind, id: z.string().trim().min(1).max(200) }).strict();
|
|
const nullableText = z.string().trim().max(10_000).nullable();
|
|
const barInput = z.object({
|
|
kind: z.enum(["volume", "percentage", "yes_no", "range"]).optional(),
|
|
name: z.string().trim().min(1).max(200),
|
|
unit: z.string().trim().max(40).nullable().optional(),
|
|
target: z.number().nullable().optional(),
|
|
low: z.number().nullable().optional(),
|
|
high: z.number().nullable().optional(),
|
|
direction: z.enum(["at_least", "at_most"]).optional(),
|
|
current: z.union([z.number(), z.boolean()]).nullable().optional(),
|
|
}).strict();
|
|
|
|
export const createAreaToolInput = z.object({
|
|
title: z.string().trim().min(1).max(200),
|
|
description: nullableText.optional(),
|
|
sortOrder: z.number().int().optional(),
|
|
}).strict();
|
|
|
|
export const updateAreaToolInput = z.object({
|
|
areaId: uuid,
|
|
title: z.string().trim().min(1).max(200).optional(),
|
|
description: nullableText.optional(),
|
|
sortOrder: z.number().int().optional(),
|
|
status: z.enum(["active", "archived"]).optional(),
|
|
}).strict();
|
|
|
|
export const deleteAreaToolInput = z.object({
|
|
areaId: uuid,
|
|
moveResponsibilitiesTo: uuid.optional(),
|
|
askAgain: z.boolean().optional(),
|
|
}).strict();
|
|
|
|
export const createResponsibilityToolInput = z.object({
|
|
title: z.string().trim().min(1).max(200),
|
|
ownerUserId: z.string().trim().min(1).max(200).optional(),
|
|
areaId: uuid.optional(),
|
|
areaTitle: z.string().trim().min(1).max(200).optional(),
|
|
description: nullableText.optional(),
|
|
standard: nullableText.optional(),
|
|
bar: barInput.optional(),
|
|
runByAgentId: uuid.optional(),
|
|
evidence: nullableText.optional(),
|
|
status: z.enum(["active", "proposed"]).optional(),
|
|
fileItems: z.array(toolItem).max(50).optional(),
|
|
}).strict().refine((value) => !(value.areaId && value.areaTitle), { message: "Send areaId or areaTitle, not both" });
|
|
|
|
export const updateResponsibilityToolInput = z.object({
|
|
responsibilityId: uuid,
|
|
title: z.string().trim().min(1).max(200).optional(),
|
|
description: nullableText.optional(),
|
|
standard: nullableText.optional(),
|
|
bar: barInput.nullable().optional(),
|
|
areaId: uuid.nullable().optional(),
|
|
areaTitle: z.string().trim().min(1).max(200).optional(),
|
|
runByAgentId: uuid.nullable().optional(),
|
|
sortOrder: z.number().int().optional(),
|
|
healthOverride: z.enum(["behind", "at_risk", "on_track"]).nullable().optional(),
|
|
healthNote: nullableText.optional(),
|
|
status: z.enum(["active", "proposed", "let_go", "dismissed"]).optional(),
|
|
}).strict().refine((value) => !(value.areaId !== undefined && value.areaTitle), { message: "Send areaId or areaTitle, not both" });
|
|
|
|
export const deleteResponsibilityToolInput = z.object({ responsibilityId: uuid, askAgain: z.boolean().optional() }).strict();
|
|
|
|
export const fileUnderResponsibilityToolInput = z.object({
|
|
responsibilityId: uuid,
|
|
items: z.array(toolItem).min(1).max(50),
|
|
moveFrom: z.union([uuid, z.literal("all")]).optional(),
|
|
}).strict();
|
|
|
|
export const removeFromResponsibilityToolInput = z.object({
|
|
responsibilityId: uuid,
|
|
items: z.array(toolItem).min(1).max(50),
|
|
}).strict();
|
|
|
|
function barPatch(input: z.infer<typeof barInput> | null) {
|
|
if (input === null) {
|
|
// Every metric input empty and no reading: the route clears the metric (it reads as not measured).
|
|
return { metricName: null, metricUnit: null, metricTarget: null, metricLow: null, metricHigh: null, metricDirection: null, metricCurrent: null };
|
|
}
|
|
return {
|
|
...(input.kind !== undefined ? { metricKind: input.kind } : {}),
|
|
metricName: input.name,
|
|
...(input.unit !== undefined ? { metricUnit: input.unit } : {}),
|
|
...(input.target !== undefined ? { metricTarget: input.target } : {}),
|
|
...(input.low !== undefined ? { metricLow: input.low } : {}),
|
|
...(input.high !== undefined ? { metricHigh: input.high } : {}),
|
|
...(input.direction !== undefined ? { metricDirection: input.direction } : {}),
|
|
...(input.current !== undefined ? { metricCurrent: input.current } : {}),
|
|
};
|
|
}
|
|
|
|
/** Resolve tool items to the route's ids: a task may be given by identifier. */
|
|
async function resolveItems(call: ApiCall, items: ReadonlyArray<z.infer<typeof toolItem>>) {
|
|
return Promise.all(items.map(async (item) => {
|
|
if (item.kind === "task" && !uuid.safeParse(item.id).success) {
|
|
const issue = await call("GET", `/issues/${encodeURIComponent(item.id)}`) as { id: string };
|
|
return { kind: item.kind, id: issue.id };
|
|
}
|
|
if (!uuid.safeParse(item.id).success) throw new HttpError(422, `A ${item.kind} id must be a UUID`);
|
|
return { kind: item.kind, id: item.id };
|
|
}));
|
|
}
|
|
|
|
function areaResult(area: ResponsibilityArea) {
|
|
return { id: area.id, title: area.title, description: area.description, status: area.status };
|
|
}
|
|
|
|
async function createArea(call: ApiCall, companyId: string, args: unknown) {
|
|
const input = createAreaToolInput.parse(args);
|
|
const meta: ApiMeta = {};
|
|
const area = await call("POST", `/companies/${encodeURIComponent(companyId)}/responsibility-areas`, input, meta) as ResponsibilityArea;
|
|
return {
|
|
area: areaResult(area),
|
|
...(area.status === "proposed" ? { note: "Saved as a proposal: this run works for no member of the company, so a person must confirm it." } : undoNote(meta)),
|
|
};
|
|
}
|
|
|
|
async function updateArea(call: ApiCall, args: unknown) {
|
|
const { areaId, ...patch } = updateAreaToolInput.parse(args);
|
|
const meta: ApiMeta = {};
|
|
const area = await call("PATCH", `/responsibility-areas/${encodeURIComponent(areaId)}`, patch, meta) as ResponsibilityArea;
|
|
return { area: areaResult(area), ...undoNote(meta) };
|
|
}
|
|
|
|
type InteractionRow = {
|
|
id: string;
|
|
kind: string;
|
|
status: string;
|
|
createdAt: string;
|
|
createdByAgentId?: string | null;
|
|
payload?: { target?: { type?: string; key?: string } };
|
|
};
|
|
|
|
/**
|
|
* The person's confirmation for one permanent delete, as a card on the
|
|
* current task: accepted (the delete may run), pending, declined, or newly
|
|
* posted. A declined card is asked again only with `askAgain`.
|
|
*/
|
|
async function deletionConfirmation(call: ApiCall, input: {
|
|
issueId: string;
|
|
/** Only this agent's own cards count: the delete route accepts no other agent's. */
|
|
agentId: string;
|
|
key: string;
|
|
label: string;
|
|
prompt: string;
|
|
details: string;
|
|
askAgain?: boolean;
|
|
}): Promise<{ state: "accepted" | "pending" | "declined" | "posted"; interactionId: string | null }> {
|
|
const issue = encodeURIComponent(input.issueId);
|
|
const cards = (await call("GET", `/issues/${issue}/interactions`) as InteractionRow[])
|
|
.filter((card) => card.kind === "request_confirmation" && card.createdByAgentId === input.agentId
|
|
&& card.payload?.target?.type === "custom" && card.payload.target.key === input.key)
|
|
.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
|
|
const latest = cards[0];
|
|
if (latest?.status === "accepted") return { state: "accepted", interactionId: latest.id };
|
|
if (latest?.status === "pending") return { state: "pending", interactionId: latest.id };
|
|
if (latest && !input.askAgain) return { state: "declined", interactionId: latest.id };
|
|
const posted = await call("POST", `/issues/${issue}/interactions`, {
|
|
kind: "request_confirmation",
|
|
idempotencyKey: `${input.key}:${cards.length + 1}`,
|
|
title: input.label,
|
|
resolverPolicy: "human_only",
|
|
continuationPolicy: "wake_assignee",
|
|
payload: {
|
|
version: 1,
|
|
prompt: input.prompt,
|
|
detailsMarkdown: input.details,
|
|
acceptLabel: "Delete",
|
|
rejectLabel: "Keep it",
|
|
target: { type: "custom", key: input.key, label: input.label.slice(0, 120) },
|
|
},
|
|
}) as { id: string };
|
|
return { state: "posted", interactionId: posted.id };
|
|
}
|
|
|
|
function awaiting(state: "pending" | "posted" | "declined", interactionId: string | null, what: string) {
|
|
if (state === "declined") {
|
|
return { deleted: false, status: "declined", confirmationId: interactionId,
|
|
next: `The person chose to keep ${what}. Do not delete it; send askAgain: true only if they ask you to delete it again.` };
|
|
}
|
|
return { deleted: false, status: "awaiting_confirmation", confirmationId: interactionId,
|
|
next: `A permanent delete needs the person's yes. ${state === "posted" ? "A confirmation card is now" : "The confirmation card is still"} on this task. Tell them, then stop; when they accept, you are woken: call this tool again with the same arguments to delete ${what}.` };
|
|
}
|
|
|
|
async function deleteArea(call: ApiCall, companyId: string, issueId: string, agentId: string, args: unknown) {
|
|
const input = deleteAreaToolInput.parse(args);
|
|
const areas = await call("GET", `/companies/${encodeURIComponent(companyId)}/responsibility-areas?includeArchived=true`) as ResponsibilityArea[];
|
|
const area = areas.find((entry) => entry.id === input.areaId);
|
|
if (!area) throw new HttpError(404, "Area not found");
|
|
const destination = input.moveResponsibilitiesTo ? areas.find((entry) => entry.id === input.moveResponsibilitiesTo) : null;
|
|
if (input.moveResponsibilitiesTo && !destination) throw new HttpError(404, "Area to move responsibilities to not found");
|
|
const confirmation = await deletionConfirmation(call, {
|
|
issueId,
|
|
agentId,
|
|
key: `responsibility-area-delete:${input.areaId}`,
|
|
label: `Delete the area "${area.title}"`.slice(0, 240),
|
|
prompt: `Delete the area "${area.title}" permanently?`.slice(0, 1000),
|
|
details: destination
|
|
? `The area is deleted. Its responsibilities move to "${destination.title}". You cannot undo a delete.`
|
|
: "The area is deleted. Its responsibilities stay, with no area. You cannot undo a delete; archiving an area can be undone.",
|
|
askAgain: input.askAgain,
|
|
});
|
|
if (confirmation.state !== "accepted") return awaiting(confirmation.state, confirmation.interactionId, `the area "${area.title}"`);
|
|
const query = new URLSearchParams({ confirmationId: confirmation.interactionId! });
|
|
if (input.moveResponsibilitiesTo) query.set("moveResponsibilitiesTo", input.moveResponsibilitiesTo);
|
|
const removed = await call("DELETE", `/responsibility-areas/${encodeURIComponent(input.areaId)}?${query}`) as ResponsibilityArea & { movedResponsibilities?: number };
|
|
return { deleted: true, area: areaResult(removed), movedResponsibilities: removed.movedResponsibilities ?? 0 };
|
|
}
|
|
|
|
async function createResponsibility(call: ApiCall, companyId: string, args: unknown, prefix: string | null | undefined) {
|
|
const input = createResponsibilityToolInput.parse(args);
|
|
const company = encodeURIComponent(companyId);
|
|
// Not idempotent by itself: a live responsibility of the same owner with the same title is reused.
|
|
const overview = await call("GET", `/companies/${company}/responsibilities?${new URLSearchParams({
|
|
includeLetGo: "false", ...(input.ownerUserId ? { ownerUserId: input.ownerUserId } : {}),
|
|
})}`) as ResponsibilityOverview;
|
|
const same = [...overview.responsibilities, ...overview.proposed]
|
|
.find((row) => row.status !== "let_go" && row.title.trim().toLowerCase() === input.title.trim().toLowerCase());
|
|
if (same) {
|
|
// A retry after a failed filing step files the items it did not reach; filing is idempotent.
|
|
const meta: ApiMeta = {};
|
|
const filed = input.fileItems?.length
|
|
? await call("POST", `/responsibilities/${encodeURIComponent(same.id)}/file`, { items: await resolveItems(call, input.fileItems) }, meta) as { filed: unknown[] }
|
|
: null;
|
|
return { created: false, responsibility: summary(same, prefix),
|
|
...(filed ? { filedItems: filed.filed.length, ...undoNote(meta) } : {}),
|
|
note: "A responsibility with this title already exists for this person; use update_responsibility to change it." };
|
|
}
|
|
const meta: ApiMeta = {};
|
|
// The server finds or makes the area by title in the same transaction as the create.
|
|
const created = await call("POST", `/companies/${company}/responsibilities`, {
|
|
title: input.title,
|
|
...(input.ownerUserId ? { ownerUserId: input.ownerUserId } : {}),
|
|
...(input.areaId ? { areaId: input.areaId } : input.areaTitle ? { areaTitle: input.areaTitle } : {}),
|
|
...(input.description !== undefined ? { description: input.description } : {}),
|
|
...(input.standard !== undefined ? { standard: input.standard } : {}),
|
|
...(input.bar ? barPatch(input.bar) : {}),
|
|
...(input.runByAgentId ? { runByAgentId: input.runByAgentId } : {}),
|
|
...(input.evidence !== undefined ? { evidence: input.evidence } : {}),
|
|
...(input.status ? { status: input.status } : {}),
|
|
}, meta) as ResponsibilityWithRollup;
|
|
const filed = input.fileItems?.length
|
|
? await call("POST", `/responsibilities/${encodeURIComponent(created.id)}/file`, { items: await resolveItems(call, input.fileItems) }, meta) as { filed: unknown[] }
|
|
: null;
|
|
return {
|
|
created: true,
|
|
responsibility: summary(created, prefix),
|
|
...(filed ? { filedItems: filed.filed.length } : {}),
|
|
...(created.status === "proposed" && input.status !== "proposed"
|
|
? { note: "Saved as a proposal: this run does not work for someone who may manage this person's responsibilities, so they must confirm it." }
|
|
: undoNote(meta)),
|
|
};
|
|
}
|
|
|
|
async function updateResponsibility(call: ApiCall, args: unknown, prefix: string | null | undefined) {
|
|
const input = updateResponsibilityToolInput.parse(args);
|
|
const patch: Record<string, unknown> = {};
|
|
for (const key of ["title", "description", "standard", "runByAgentId", "sortOrder", "healthOverride", "healthNote", "status"] as const) {
|
|
if (input[key] !== undefined) patch[key] = input[key];
|
|
}
|
|
if (input.areaId !== undefined) patch.areaId = input.areaId;
|
|
// The server finds or makes the area by title in the same transaction as the change.
|
|
if (input.areaTitle) patch.areaTitle = input.areaTitle;
|
|
if (input.bar !== undefined) Object.assign(patch, barPatch(input.bar));
|
|
if (Object.keys(patch).length === 0) throw new HttpError(422, "Send at least one field to change");
|
|
const meta: ApiMeta = {};
|
|
const updated = await call("PATCH", `/responsibilities/${encodeURIComponent(input.responsibilityId)}`, patch, meta) as ResponsibilityWithRollup;
|
|
return {
|
|
responsibility: summary(updated, prefix),
|
|
...undoNote(meta),
|
|
...(input.bar !== undefined ? { barNote: BAR_NOTE } : {}),
|
|
};
|
|
}
|
|
|
|
async function deleteResponsibility(call: ApiCall, issueId: string, agentId: string, args: unknown) {
|
|
const input = deleteResponsibilityToolInput.parse(args);
|
|
const id = encodeURIComponent(input.responsibilityId);
|
|
const row = await call("GET", `/responsibilities/${id}`) as ResponsibilityDetail;
|
|
const filed = row.projects.length + row.tasks.filter((task) => task.membership === "direct").length
|
|
+ row.routines.filter((routine) => routine.membership === "direct").length;
|
|
const confirmation = await deletionConfirmation(call, {
|
|
issueId,
|
|
agentId,
|
|
key: `responsibility-delete:${input.responsibilityId}`,
|
|
label: `Delete "${row.title}"`.slice(0, 240),
|
|
prompt: `Delete the responsibility "${row.title}" permanently?`.slice(0, 1000),
|
|
details: [
|
|
"Its bar, its metric history and its status reports are deleted. You cannot undo a delete.",
|
|
filed > 0 ? `${filed} filed ${filed === 1 ? "item stays" : "items stay"}, but ${filed === 1 ? "it is" : "they are"} no longer under this responsibility.` : null,
|
|
"To stop it without losing it, let it go instead.",
|
|
].filter(Boolean).join("\n\n"),
|
|
askAgain: input.askAgain,
|
|
});
|
|
if (confirmation.state !== "accepted") return awaiting(confirmation.state, confirmation.interactionId, `"${row.title}"`);
|
|
await call("DELETE", `/responsibilities/${id}?${new URLSearchParams({ confirmationId: confirmation.interactionId! })}`);
|
|
return { deleted: true, responsibility: { id: row.id, title: row.title } };
|
|
}
|
|
|
|
async function fileUnderResponsibility(call: ApiCall, args: unknown) {
|
|
const input = fileUnderResponsibilityToolInput.parse(args);
|
|
const items = await resolveItems(call, input.items);
|
|
const meta: ApiMeta = {};
|
|
const result = await call("POST", `/responsibilities/${encodeURIComponent(input.responsibilityId)}/file`, {
|
|
items, ...(input.moveFrom ? { moveFrom: input.moveFrom } : {}),
|
|
}, meta) as { filed: Array<{ link: { id: string }; created: boolean }>; unfiled: Array<{ responsibilityId: string }> };
|
|
return {
|
|
responsibilityId: input.responsibilityId,
|
|
filed: result.filed.filter((entry) => entry.created).length,
|
|
alreadyFiled: result.filed.filter((entry) => !entry.created).length,
|
|
movedFrom: [...new Set(result.unfiled.map((link) => link.responsibilityId))],
|
|
...undoNote(meta),
|
|
};
|
|
}
|
|
|
|
async function removeFromResponsibility(call: ApiCall, args: unknown) {
|
|
const input = removeFromResponsibilityToolInput.parse(args);
|
|
const items = await resolveItems(call, input.items);
|
|
const meta: ApiMeta = {};
|
|
const result = await call("POST", `/responsibilities/${encodeURIComponent(input.responsibilityId)}/unfile`, { items }, meta) as { unfiled: unknown[] };
|
|
return {
|
|
responsibilityId: input.responsibilityId,
|
|
unfiled: result.unfiled.length,
|
|
notFiledThere: items.length - result.unfiled.length,
|
|
...undoNote(meta),
|
|
};
|
|
}
|
|
|
|
/** All transports use the normal authenticated API, including its validation and audit path. */
|
|
export async function callResponsibilityTool(input: {
|
|
name: ResponsibilityToolName;
|
|
arguments: Record<string, unknown>;
|
|
apiUrl: string;
|
|
token: string;
|
|
companyId: string;
|
|
/** The run's task: confirmation cards for a permanent delete are posted there. */
|
|
issueId: string;
|
|
/** The run's agent: only its own confirmation cards authorize its deletes. */
|
|
agentId: string;
|
|
/** The company's issue prefix; results then carry page hrefs. */
|
|
companyPrefix?: string | null;
|
|
}, fetcher: typeof fetch = fetch) {
|
|
const call = apiCaller(input, fetcher);
|
|
switch (input.name) {
|
|
case "list_responsibilities": return listResponsibilities(call, input.companyId, input.arguments, input.companyPrefix);
|
|
case "get_responsibility": return getResponsibility(call, input.arguments, input.companyPrefix);
|
|
case "find_responsibilities_for": return findResponsibilitiesFor(call, input.companyId, input.arguments, input.companyPrefix);
|
|
case "create_area": return createArea(call, input.companyId, input.arguments);
|
|
case "update_area": return updateArea(call, input.arguments);
|
|
case "delete_area": return deleteArea(call, input.companyId, input.issueId, input.agentId, input.arguments);
|
|
case "create_responsibility": return createResponsibility(call, input.companyId, input.arguments, input.companyPrefix);
|
|
case "update_responsibility": return updateResponsibility(call, input.arguments, input.companyPrefix);
|
|
case "delete_responsibility": return deleteResponsibility(call, input.issueId, input.agentId, input.arguments);
|
|
case "file_under_responsibility": return fileUnderResponsibility(call, input.arguments);
|
|
case "remove_from_responsibility": return removeFromResponsibility(call, input.arguments);
|
|
}
|
|
}
|