Files
PaperClipAI/ui/src/components/InteractionGovernancePanel.tsx
T
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

312 lines
13 KiB
TypeScript

import { Fragment } from "react";
import {
ISSUE_THREAD_INTERACTION_KINDS,
normalizeIssueThreadInteractionResolverPolicy,
type InteractionResolverGovernance,
type IssueThreadInteractionCanonicalResolverPolicy,
type IssueThreadInteractionKind,
type IssueThreadInteractionResolverPolicy,
} from "@paperclipai/shared";
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
import { resolverPolicyLabel } from "../lib/interaction-audience";
const INTERACTION_KIND_LABELS: Record<IssueThreadInteractionKind, string> = {
suggest_tasks: "Suggested tasks",
ask_user_questions: "Ask user questions",
request_confirmation: "Confirmations",
request_checkbox_confirmation: "Checkbox confirmations",
request_item_verdicts: "Item verdicts",
connection_intent: "Connection requests",
suggest_routine: "Routine offers",
propose_responsibility_bar: "Proposed bars",
propose_automation: "Proposed automations",
propose_dashboard_changes: "Proposed dashboard changes",
};
/**
* Sentinel for "no override" — Radix Select disallows empty-string item values.
* Under the open-default contract (PAP-17280) an absent override *is* the open
* audience, so this sentinel is what a company sees selected until it
* deliberately narrows a kind.
*/
export const GOVERNANCE_UNSET = "default";
export type GovernanceSelectValue = typeof GOVERNANCE_UNSET | IssueThreadInteractionResolverPolicy;
export type GovernanceField = "defaultPolicy" | "cap";
/**
* Only *narrowing* policies are offered. `anyone` is the product default, so
* requesting it as a default override is a no-op, and capping at `anyone` cannot
* narrow anything — both collapse into the unset sentinel, which is presented as
* the visible default.
*/
const NARROWING_POLICIES: readonly IssueThreadInteractionCanonicalResolverPolicy[] = [
"not_creator",
"human_only",
];
const UNSET_LABELS: Record<GovernanceField, string> = {
defaultPolicy: "Anyone (default)",
cap: "No cap",
};
const UNSET_EFFECTS: Record<GovernanceField, string> = {
defaultPolicy: "New cards are open — the board or any agent can respond, including the one that asked.",
cap: "A request keeps whatever audience it asks for.",
};
const DEFAULT_POLICY_EFFECTS: Record<IssueThreadInteractionCanonicalResolverPolicy, string> = {
anyone: UNSET_EFFECTS.defaultPolicy,
not_creator: "New cards exclude the agent that created them, so the answer comes from someone else.",
human_only: "New cards wait for a person on the board. Agents are turned away.",
};
const CAP_EFFECTS: Record<IssueThreadInteractionCanonicalResolverPolicy, string> = {
anyone: UNSET_EFFECTS.cap,
not_creator: "Even a card that asks for Anyone is narrowed to exclude its creator.",
human_only: "Every card of this kind waits for a person, whatever it asked for.",
};
function governanceOptions(field: GovernanceField): {
value: GovernanceSelectValue;
label: string;
effect: string;
}[] {
const effects = field === "cap" ? CAP_EFFECTS : DEFAULT_POLICY_EFFECTS;
return [
{ value: GOVERNANCE_UNSET, label: UNSET_LABELS[field], effect: UNSET_EFFECTS[field] },
...NARROWING_POLICIES.map((policy) => ({
value: policy as GovernanceSelectValue,
label: resolverPolicyLabel(policy),
effect: effects[policy],
})),
];
}
/**
* The label a *closed* trigger must show. Derived from the value rather than
* looked up in the option list so an out-of-list value (a raw `anyone`, say)
* still renders a complete, truthful label instead of falling back to a lie.
*/
export function governanceValueLabel(field: GovernanceField, value: GovernanceSelectValue): string {
return value === GOVERNANCE_UNSET ? UNSET_LABELS[field] : resolverPolicyLabel(value);
}
/**
* Map a persisted override onto a select value. A stored `anyone` — including
* the deprecated `board_or_agents` alias — is the open default, so it shows as
* the unset sentinel rather than as a narrowing override.
*/
export function toGovernanceSelectValue(
policy: IssueThreadInteractionResolverPolicy | undefined,
): GovernanceSelectValue {
if (!policy) return GOVERNANCE_UNSET;
const canonical = normalizeIssueThreadInteractionResolverPolicy(policy);
return canonical === "anyone" ? GOVERNANCE_UNSET : canonical;
}
/**
* Apply a single (kind, field) change to a governance map immutably, pruning
* empty entries so the persisted object stays sparse (only real overrides).
*/
export function applyGovernanceChange(
current: InteractionResolverGovernance,
kind: IssueThreadInteractionKind,
field: GovernanceField,
value: GovernanceSelectValue,
): InteractionResolverGovernance {
const next: InteractionResolverGovernance = { ...current };
const entry = { ...(next[kind] ?? {}) };
if (value === GOVERNANCE_UNSET) {
delete entry[field];
} else {
entry[field] = value;
}
if (entry.defaultPolicy === undefined && entry.cap === undefined) {
delete next[kind];
} else {
next[kind] = entry;
}
return next;
}
function GovernanceSelect({
field,
value,
onChange,
disabled,
testId,
ariaLabel,
mobileLabel,
}: {
field: GovernanceField;
value: GovernanceSelectValue;
onChange: (value: GovernanceSelectValue) => void;
disabled?: boolean;
testId?: string;
ariaLabel: string;
mobileLabel: string;
}) {
const options = governanceOptions(field);
return (
<div className="min-w-0">
{/*
* Below `sm` the governance grid collapses to a single column (see the
* grid classes on the panel), detaching each select from its column
* header. Surface a mobile-only inline label so the control stays
* self-describing for sighted users, and always carry `aria-label` for
* screen-reader pairing. WCAG 2.1 SC 1.4.10 (Reflow) — design review R2.
*/}
<span className="mb-1 block text-xs font-medium text-muted-foreground uppercase tracking-wide sm:hidden">
{mobileLabel}
</span>
<Select value={value} onValueChange={(v) => onChange(v as GovernanceSelectValue)} disabled={disabled}>
<SelectTrigger
size="sm"
aria-label={ariaLabel}
// 208px is sized for the longest label the control can hold —
// `Anyone except creator` needs ~150px of text room, and 170px only
// left 122px after padding, gap and chevron, so it clipped even once
// the effect sentence was gone (PAP-17297).
className="w-full min-w-0 text-xs sm:w-(--sz-208px)"
data-testid={testId}
>
{/*
* Explicit children, not the default `<SelectValue />`. Radix portals
* the selected item's *whole* subtree into an empty value node, which
* dragged each option's effect sentence into the closed trigger and
* clipped the selected label (desktop truncated the prose, mobile cut
* `Anyone (default)` mid-label — PAP-17293/PAP-17297). Passing children
* sets `valueNodeHasChildren`, which suppresses that portal, so the
* trigger shows exactly the label and nothing else.
*/}
<SelectValue>{governanceValueLabel(field, value)}</SelectValue>
</SelectTrigger>
{/*
* Cap the option list so the effect sentences wrap instead of stretching
* the popover past a ~390px viewport (WCAG 2.1 SC 1.4.10 Reflow).
*/}
<SelectContent className="max-w-(--sz-280px) sm:max-w-(--sz-360px)">
{options.map((option) => (
<SelectItem
key={option.value}
value={option.value}
// Keyboard typeahead matches on `textValue` when given; without it
// Radix would match against the effect prose too.
textValue={option.label}
className="text-xs"
>
{/*
* Effect preview lives inside the option so the consequence of a
* narrowing choice is legible at the moment of choosing, not only
* after saving (PAP-17280).
*/}
<span className="flex min-w-0 flex-col gap-0.5">
<span>{option.label}</span>
<span className="text-(length:--text-micro) text-muted-foreground">
{option.effect}
</span>
</span>
</SelectItem>
))}
</SelectContent>
</Select>
</div>
);
}
/**
* Company-level interaction governance: the per-kind default audience and cap.
*
* The open default is the headline — interactions are resolvable by anyone in
* the company unless a row here narrows them — so the panel only offers
* narrowing choices and never presents an unrestricted card as board-required.
*/
export function InteractionGovernancePanel({
governance,
onChange,
isPending,
errorMessage,
}: {
governance: InteractionResolverGovernance;
onChange: (kind: IssueThreadInteractionKind, field: GovernanceField, value: GovernanceSelectValue) => void;
isPending?: boolean;
errorMessage?: string | null;
}) {
return (
<div className="space-y-4" data-testid="company-settings-interaction-governance-section">
<div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
Interaction governance
</div>
<div className="space-y-4">
<p className="text-sm text-muted-foreground">
Thread interactions are open by default:{" "}
<span className="font-medium text-foreground">Anyone</span> in the organization — the
board or any agent, including the one that asked — can respond. Narrow a kind
only when you need to.{" "}
<span className="font-medium text-foreground">Default policy</span> is the
audience new cards get when the requester does not ask for one;{" "}
<span className="font-medium text-foreground">Cap</span> narrows every request of
that kind and can never widen one. Tool-approval confirmations always stay{" "}
<span className="font-medium text-foreground">Human only</span>.
</p>
{/*
* Responsive: below `sm` the row collapses to a single column so the
* two 170px selects never force horizontal overflow on a ~390px
* viewport (WCAG 2.1 SC 1.4.10 Reflow — design review R2). Each kind
* then stacks as: label → Default policy → Cap, each full-width with
* its own inline label. At `sm`+ it restores the aligned 3-col grid.
*/}
<div className="grid grid-cols-1 gap-y-4 sm:grid-cols-[1fr_auto_auto] sm:items-center sm:gap-x-4 sm:gap-y-2.5">
<div className="hidden text-xs font-medium text-muted-foreground uppercase tracking-wide sm:block">
Kind
</div>
<div className="hidden text-xs font-medium text-muted-foreground uppercase tracking-wide sm:block">
Default policy
</div>
<div className="hidden text-xs font-medium text-muted-foreground uppercase tracking-wide sm:block">
Cap
</div>
{ISSUE_THREAD_INTERACTION_KINDS.filter((kind) => kind !== "suggest_routine" && kind !== "propose_responsibility_bar" && kind !== "propose_automation" && kind !== "propose_dashboard_changes").map((kind) => {
// Routine offers and proposed bars are always answered by a person; there is no audience to govern.
const entry = governance[kind] ?? {};
const kindLabel = INTERACTION_KIND_LABELS[kind];
return (
<Fragment key={kind}>
<div className="text-sm font-medium sm:font-normal">{kindLabel}</div>
<GovernanceSelect
field="defaultPolicy"
testId={`governance-${kind}-default`}
ariaLabel={`Default resolver audience for ${kindLabel}`}
mobileLabel="Default policy"
value={toGovernanceSelectValue(entry.defaultPolicy)}
disabled={isPending}
onChange={(v) => onChange(kind, "defaultPolicy", v)}
/>
<GovernanceSelect
field="cap"
testId={`governance-${kind}-cap`}
ariaLabel={`Resolver cap for ${kindLabel}`}
mobileLabel="Cap"
value={toGovernanceSelectValue(entry.cap)}
disabled={isPending}
onChange={(v) => onChange(kind, "cap", v)}
/>
</Fragment>
);
})}
</div>
{errorMessage ? (
<span className="text-xs text-destructive">{errorMessage}</span>
) : null}
</div>
</div>
);
}