Commit Graph
3 Commits
Author SHA1 Message Date
575ef12575 feat(responsibilities): file company skills under responsibilities (#22275)
## 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>
2026-11-19 09:30:49 -06:00
DottaandClaude Opus 5.5 c0aa7751f8 feat(responsibilities): let agents change areas and responsibilities for their person, with undo (#22261)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - People keep their areas and responsibilities in Paperclip
(experimental, `enableResponsibilities`). #22253 lets agents read them.
> - Agents can still only propose. They cannot rename or archive an
area, change an active responsibility, let one go, or move work between
responsibilities in one step.
> - A person who says "file my weekly routines under Sales" must then do
it by hand.
> - The maintainer chose this rule: an agent may make each change that
its person could make, the person can undo it from the Dashboard
history, and a permanent delete still needs the person's yes on a card.
> - This pull request adds eight change tools and the server rules
behind them.
> - The benefit is that an agent maps work to responsibilities for the
person, and the person keeps control through undo and the delete card.

## Linked Issues or Issue Description

Refs #22253 (phase 1; this pull request is stacked on it).

**Subsystem affected**

Server (responsibility and area routes, Dashboard versions, native
runner tool authority), shared validators and Dashboard types, the
native runner tool catalog, the `paperclip` skill, and the Dashboard
history UI.

**Problem or motivation**

An agent that works for a person can only propose areas and
responsibilities. It cannot change active ones, archive or delete them,
or move filed work in one step. Unfiling needs link IDs. There is no way
for the person to undo an agent's change.

**Proposed solution**

When an agent acts for the person its run works for (`onBehalfOfUserId`)
and that person directed the run (the run's own task is one they made,
such as their chat, or their own message woke it; parent tasks do not
count), apply that person's own rights: their own responsibilities, or
anyone's for a company owner or admin; areas for any active member. Save
each such change as a version of the person's Dashboard, so the existing
history and Undo line show it under the agent's name. Make a permanent
delete wait for an accepted confirmation card that the agent posted. Add
`file` and `unfile` routes that take items by kind and ID, with an
optional move.

**Alternatives considered**

One card for every change, or propose-only. The maintainer chose "act
for me, with undo". A separate undo journal would need a new table and a
new UI; Dashboard versions already have both. A new version cause needs
a check-constraint migration; this change uses `change_set` with no
`interactionId` instead.

## What Changed

- Add tools `create_area`, `update_area`, `delete_area`,
`create_responsibility`, `update_responsibility`,
`delete_responsibility`, `file_under_responsibility` and
`remove_from_responsibility`. They are standard-mode only and hidden
while Responsibilities is off.
- Add the writer rule for agents in `routes/agent-person-authz.ts`
(`agentPersonInCompany`, `agentActsForResponsibilityOwner`), used by
`routes/responsibilities.ts` and `routes/responsibility-areas.ts`. The
person must have directed the run: a person can name anyone as a task's
responsible person, and a run can also work for a routine's person or
the company default, so those runs do not borrow that person's rights.
An agent with no such person keeps the old propose-only rules.
- The response names only the version of the responsibility's owner (for
area changes, the acting person's), and `X-Paperclip-Dashboard-Owner`
says whose history holds it; tools return `dashboardOwnerUserId`. A
change Undo cannot reverse (the name, description, order or un-archiving
of an area other people's proposed or active responsibilities share)
saves no version and is not reported as undoable.
- `/file` without `moveFrom` follows the `/links` rule, so
`create_responsibility` with `fileItems` works for a proposal.
- A title-only create is allowed for an acting agent. It is active by
default and records the agent in `proposedByAgentId`.
- Add `responsibility-agent-changes.ts`. In one transaction that holds
each affected owner's Dashboard lock, it saves the dashboard before the
change (when a person changed it by hand), runs the change on services
bound to that transaction, and saves the result as a `change_set`
version by that agent. The response names the version in
`X-Paperclip-Dashboard-Version`. The tools say Undo only when a version
was saved.
- Dashboard snapshots now also hold each responsibility's filed items,
description, "run by" agent, evidence, health override and note, and
each area's description (optional fields). Restore puts them back. Older
versions still restore as before. A matching older version is upgraded
in place, so the first change after it compares and undoes in full.
- Create and update accept `areaTitle`. The server finds or makes that
area in the same transaction, so a refused change leaves no area. Agent
creates reuse a live responsibility with the same title under a lock, so
retries and parallel calls make no copies.
- Add `POST /api/responsibilities/:id/file` (`items`, optional
`moveFrom`: an ID or `all`) and `POST /api/responsibilities/:id/unfile`
(`items`), each in one transaction.
- Agent deletes need `confirmationId`: an accepted
`request_confirmation` card that this agent posted, with target key
`responsibility-delete:<id>` or `responsibility-area-delete:<id>`.
Someone who may manage the owner must accept it, on the card or by a
verified chat reply. The tools post the card (named after the item),
return `awaiting_confirmation`, and delete on the next call after
acceptance.
- `DELETE /api/responsibility-areas/:id` accepts
`moveResponsibilitiesTo`. Area changes and deletes save versions for
everyone whose Dashboard shows the area.
- Agent activity details now include `onBehalfOfUserId`. The Dashboard
history shows "<agent>, for you" for these versions.
`ResponsibilityDashboardVersionSummary` now has `interactionId`.
- Update the OpenAPI registry and metadata, the `search_api` tool
pointers, the skill, the API reference, the chat directive, the
operation-groups spec, and the pinned counts and SDK source pins.

## Verification

- Server: `vitest run` of the `responsibilit*` tests,
`responsibility-tools.test.ts`, `openapi-routes`, `runner-api*`,
`paperclip-runner-tool-authority` and `task-markdown` all pass. New
tests cover these cases: acting-agent create, update and undo; file,
move and undo; the rule for a person who may not manage the owner;
delete only after an accepted card, including a verified chat reply;
area delete with move and a version for the other owner; undo of a
health override, an area description and an un-archived empty area;
upgrade of an older version; an area by title that a refused change
rolls back; parallel creates.
- UI: `DashboardEditModule.test.tsx` and
`responsibility-dashboard.test.ts` passed. `pnpm --filter
@paperclipai/ui typecheck` passed.
- Server `node scripts/typecheck-layers.mjs` passed.
- Runner: catalog, semantic-tool, eval, protocol-action and
permission-policy tests (284) passed. All generator checks pass.
- I did not run the browser e2e suite locally.

## Risks

- Medium. Agents that work for a person can now change and archive that
person's responsibilities and areas without a card. Every change is a
Dashboard version that the person can restore, and a delete still needs
the card.
- Undo restores titles, sentences, areas, order, status, filed items,
description and the "run by" agent. It does not restore a bar or metric
change; those stay in the metric history.
- A restore of a version from before this change does not touch filed
items, which matches the earlier behavior.
- Undo of a rename or archive of an area that other people also use
keeps its name, as the existing restore rule does for shared areas.
- Manual edits do not take the Dashboard lock. A person's edit that
commits while an agent's change is open can appear in that agent's
version.
- Changes to proposed or let-go responsibilities are not on a Dashboard,
so they cannot be undone there. The tools say so.

## 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>
2026-11-19 09:29:11 -06:00
43b2d8be22 feat(dashboard): add an experimental areas and responsibilities dashboard (#22069)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The dashboard is the first page a person sees in a company
> - The classic dashboard shows agents, runs, costs and recent tasks
> - It does not show what the person is responsible for, or if that work
goes well
> - People think in areas, such as Fundraising or Customers, and in the
things they own in each area
> - This pull request adds a dashboard built on areas and
responsibilities, behind an experimental setting that is off by default
> - The benefit is that a person sees what they own, how it is going,
and what agents do for it, on one page

## Linked Issues or Issue Description

No public issue exists for this work. The description follows the
feature request template.

**Subsystem affected**

Dashboard, navigation, the task conversation, routines, and the instance
experimental settings.

**Problem or motivation**

The classic dashboard counts agents and tasks. It does not say what a
person owns or if it goes well. People who run a company with agents
want to see their areas, the responsibilities in each area, the bar each
one must meet, and the agents and routines that serve it.

**Proposed solution**

A person owns responsibilities. Each responsibility belongs to an area
and has a bar, a number to reach. Projects, tasks and routines link to a
responsibility, and the page shows its status from those links. An agent
can interview the person and draft the dashboard. The person accepts or
declines each change, and any change can be undone from a saved version.

**Alternatives considered**

Add the same data to the classic dashboard. That page is a fixed set of
cards for company activity, so a second, person-centred page is clearer.
The setting lets a person pick one of the two.

**Roadmap alignment**

This is an experimental feature behind `enableResponsibilities`. It is
off by default and changes nothing for a person who leaves it off.

## What Changed

- Add the setting "Areas & Responsibilities dashboard"
(`enableResponsibilities`, off by default). On, Dashboard in the sidebar
opens the new page, and the classic dashboard link is not shown in the
sidebars or the command palette. Off, nothing changes.
- Add tables and migrations 0492 to 0497 for areas, responsibilities,
links to work, metrics, status reports, saved dashboard versions, and
model-call records for summaries.
- Add the API: areas, responsibilities, links, bars, metrics, status
reports, summaries, runs, automation, and the dashboard conversation
with versions and undo. Each route checks company access and writes to
the activity log.
- Add four task conversations with an agent: about a bar, about an
automation, about a routine, and about the whole dashboard. The agent
proposes a change. Nothing applies until a person accepts it.
- Add standing checks: routines that an agent carries out on its
heartbeat and reports.
- Add the Dashboard page: search, counts, areas that open and close, a
primary New area button, and a message box at the bottom of the page.
Add the responsibility page with its bar, metrics, work and routines.
- Add the Paperclip skill sections and runner API entries that let an
agent use these routes. The runner skill inventory is regenerated (166
to 174 rows).
- Keep the new runner API tests in their own file so
`runner-api.test.ts` stays at 985 lines.
- Onboarding is not changed. The onboarding changes that build on this
work are a separate pull request.

## Verification

- Type checks pass for `packages/db`, `packages/shared`, `server` (all
layers) and `ui`.
- `pnpm --filter @paperclipai/db check:migrations` passes. A new
`drizzle-kit generate` run produces no further change.
- Tests for every changed file pass: 26 server test files (3,009 tests),
116 UI test files (1,991 tests) and 28 shared test files (432 tests).
- The runner capability inventory checks pass.
- I started the app on a local database that already held earlier data.
Master's new migrations and these migrations applied without error. With
the setting on, the Dashboard and a responsibility page loaded with no
console or server errors. The More menu and the command palette show one
Dashboard.
- I did not run `pnpm verify`, the full local suite, or the browser
suites. Required CI covers them.
- The agent conversations are tested with simulated agents. No real
model has run them.

## Risks

- Medium. The change is large, and the setting is off by default. With
it off, the new routes refuse requests and the UI is unchanged.
- Migrations only add tables and columns. Two replace a CHECK
constraint, and one builds an index `CONCURRENTLY`. These two have the
`online_compatible` override with a reason in the file, and the second
one is listed in `MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS`.
- Master can add migrations before this merges. The migrations then need
new numbers.
- `responsibilities.ts` (1,663 lines), `responsibility-summaries.ts`
(1,239 lines) and one Storybook fixture file (1,305 lines) are new files
over 1,000 lines. They each keep one cohesive unit together: the service
for one table family, the model-call path for summaries, and the
fixtures that the stories share. No existing file crosses 1,000 lines.

> 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

- Anthropic Claude: Claude Fable 5.2 (`claude-fable-5-2`) wrote most of
the change, with Claude Sonnet 5.5 (`claude-sonnet-5-5`) for the final
steps. Both used tool use, code execution and browser checks.

## 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
- [ ] 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
- [ ] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Scott Tong <scott@scottsmbpm5max.lan>
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-17 20:45:44 -08:00