Files
PaperClipAI/server/src/routes/experimental-api-paths.ts
T
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

226 lines
41 KiB
TypeScript

// Experimental routes share their runtime validators with OpenAPI discovery.
import { z } from "zod";
import * as caseSchemas from "./cases-schemas.js";
import * as sharedSchemas from "@paperclipai/shared";
export const experimentalApiPaths: readonly [string, string, z.ZodTypeAny | undefined][] = [
["post", "/api/companies/{companyId}/cases", caseSchemas.createCaseSchema],
["get", "/api/companies/{companyId}/cases", undefined],
["get", "/api/companies/{companyId}/cases/types", undefined],
["get", "/api/cases/{id}/documents/{key}", undefined],
["get", "/api/cases/{id}/documents/{key}/annotations", undefined],
["get", "/api/cases/{id}/documents/{key}/annotations/{threadId}", undefined],
["post", "/api/cases/{id}/documents/{key}/annotations", sharedSchemas.createDocumentAnnotationThreadSchema],
["post", "/api/cases/{id}/documents/{key}/annotations/{threadId}/comments", sharedSchemas.createDocumentAnnotationCommentSchema],
["patch", "/api/cases/{id}/documents/{key}/annotations/{threadId}", sharedSchemas.updateDocumentAnnotationThreadSchema],
["put", "/api/cases/{id}/documents/{key}", caseSchemas.upsertCaseDocumentSchema],
["post", "/api/cases/{id}/documents/{key}/lock", undefined],
["post", "/api/cases/{id}/documents/{key}/unlock", undefined],
["post", "/api/cases/{id}/documents/{key}/revisions/{revisionId}/restore", undefined],
["delete", "/api/cases/{id}/documents/{key}", undefined],
["post", "/api/cases/{id}/links", caseSchemas.createIssueLinkSchema],
["post", "/api/cases/{id}/attachments", undefined],
["get", "/api/cases/{id}/events", undefined],
["get", "/api/cases/{id}/documents/{key}/revisions", undefined],
["get", "/api/issues/{issueId}/cases", undefined],
["get", "/api/cases/{id}", undefined],
["patch", "/api/cases/{id}", caseSchemas.patchCaseSchema],
["get", "/api/companies/{companyId}/smoke-lab/oauth/authorize", undefined],
["post", "/api/companies/{companyId}/smoke-lab/oauth/authorize", undefined],
["post", "/api/companies/{companyId}/smoke-lab/oauth/token", undefined],
["get", "/api/companies/{companyId}/smoke-lab/oauth/userinfo", undefined],
["post", "/api/companies/{companyId}/smoke-lab/oauth/revoke", undefined],
["get", "/api/companies/{companyId}/smoke-lab/services", undefined],
["post", "/api/companies/{companyId}/smoke-lab/services/start", undefined],
["post", "/api/companies/{companyId}/smoke-lab/services/stop", undefined],
["post", "/api/companies/{companyId}/smoke-lab/install-fixtures", undefined],
["get", "/api/companies/{companyId}/smoke-lab/runs", undefined],
["post", "/api/companies/{companyId}/smoke-lab/runs", sharedSchemas.createSmokeRunSchema],
["get", "/api/companies/{companyId}/smoke-lab/runs/{runId}", undefined],
["patch", "/api/companies/{companyId}/smoke-lab/runs/{runId}", sharedSchemas.updateSmokeRunSchema],
["post", "/api/companies/{companyId}/smoke-lab/runs/{runId}/steps", sharedSchemas.recordSmokeRunStepSchema],
["post", "/api/companies/{companyId}/smoke-lab/reset", undefined],
["get", "/api/companies/{companyId}/responsibilities", undefined],
["post", "/api/companies/{companyId}/responsibilities", sharedSchemas.createResponsibilitySchema],
["get", "/api/responsibilities/{id}", undefined],
["patch", "/api/responsibilities/{id}", sharedSchemas.updateResponsibilitySchema],
["delete", "/api/responsibilities/{id}", undefined],
["post", "/api/responsibilities/{id}/links", sharedSchemas.linkResponsibilitySchema],
["delete", "/api/responsibilities/{id}/links/{linkId}", undefined],
["post", "/api/responsibilities/{id}/file", sharedSchemas.fileResponsibilityItemsSchema],
["post", "/api/responsibilities/{id}/unfile", sharedSchemas.unfileResponsibilityItemsSchema],
["post", "/api/responsibilities/{id}/delegate", sharedSchemas.delegateResponsibilitySchema],
["get", "/api/companies/{companyId}/responsibility-links/lookup", undefined],
["get", "/api/companies/{companyId}/responsibility-areas", undefined],
["post", "/api/companies/{companyId}/responsibility-areas", sharedSchemas.createResponsibilityAreaSchema],
["patch", "/api/responsibility-areas/{id}", sharedSchemas.updateResponsibilityAreaSchema],
["delete", "/api/responsibility-areas/{id}", undefined],
["get", "/api/companies/{companyId}/responsibilities/summary", undefined],
["get", "/api/responsibilities/{id}/summary", undefined],
["get", "/api/companies/{companyId}/responsibilities/automation", undefined],
["post", "/api/issues/{id}/routine-suggestions", sharedSchemas.createRoutineSuggestionSchema],
["post", "/api/issues/{id}/routine-suggestions/{interactionId}/accept", sharedSchemas.acceptRoutineSuggestionSchema],
["post", "/api/issues/{id}/routine-suggestions/{interactionId}/decline", sharedSchemas.declineRoutineSuggestionSchema],
["post", "/api/issues/{id}/repeat-as-routine", sharedSchemas.createRoutineFromTaskSchema],
["get", "/api/responsibilities/{id}/bar-conversation", undefined],
["post", "/api/responsibilities/{id}/bar-conversation", sharedSchemas.startResponsibilityBarConversationSchema],
["post", "/api/issues/{id}/bar-proposals", sharedSchemas.createResponsibilityBarProposalSchema],
["post", "/api/issues/{id}/bar-proposals/{interactionId}/accept", sharedSchemas.acceptResponsibilityBarProposalSchema],
["post", "/api/issues/{id}/bar-proposals/{interactionId}/decline", sharedSchemas.declineResponsibilityBarProposalSchema],
["get", "/api/companies/{companyId}/responsibility-dashboard", undefined],
["get", "/api/companies/{companyId}/responsibility-dashboard/versions", undefined],
["post", "/api/companies/{companyId}/responsibility-dashboard/conversation", sharedSchemas.startDashboardConversationSchema],
["post", "/api/issues/{id}/dashboard-changes", sharedSchemas.createDashboardChangeSetSchema],
["post", "/api/issues/{id}/dashboard-changes/{interactionId}/accept", sharedSchemas.acceptDashboardChangeSetSchema],
["post", "/api/issues/{id}/dashboard-changes/{interactionId}/decline", sharedSchemas.declineDashboardChangeSetSchema],
["post", "/api/responsibility-dashboard-versions/{id}/restore", sharedSchemas.restoreDashboardVersionSchema],
["get", "/api/responsibilities/{id}/metrics", undefined],
["put", "/api/responsibilities/{id}/metrics", sharedSchemas.setResponsibilityMetricsSchema],
["patch", "/api/responsibilities/{id}/metrics/{metricId}", sharedSchemas.setResponsibilityMetricDisplaySchema],
["delete", "/api/responsibilities/{id}/metrics/{metricId}", undefined],
["post", "/api/responsibilities/{id}/metrics/{metricId}/readings", sharedSchemas.recordResponsibilityMetricReadingSchema],
["get", "/api/responsibilities/{id}/runs", undefined],
["get", "/api/issues/{id}/automation-conversation", undefined],
["post", "/api/issues/{id}/automation-conversation", sharedSchemas.startAutomationConversationSchema],
["post", "/api/issues/{id}/automation-proposals", sharedSchemas.createAutomationProposalSchema],
["post", "/api/issues/{id}/automation-proposals/{interactionId}/accept", sharedSchemas.acceptAutomationProposalSchema],
["post", "/api/issues/{id}/automation-proposals/{interactionId}/decline", sharedSchemas.declineAutomationProposalSchema],
["post", "/api/routines/{id}/standing-check-results", sharedSchemas.reportStandingCheckSchema],
["get", "/api/companies/{companyId}/responsibilities/status-reports", undefined],
["get", "/api/responsibilities/{id}/status-report", undefined],
["post", "/api/responsibilities/{id}/status-report", sharedSchemas.writeResponsibilityStatusReportSchema],
["post", "/api/responsibilities/{id}/status-report/request", sharedSchemas.requestResponsibilityStatusUpdateSchema],
];
// Searchable summaries for experimental reads agents need to find. Routes not
// listed here keep the generated method-and-path summary.
export const experimentalApiDocs: Record<string, { summary: string; description: string }> = {
"GET /api/companies/{companyId}/cases": { summary: "List company cases",
description: "Lists the cases the caller can read, with each case's id, identifier, title, status and primary task (workIssueId)." },
"GET /api/issues/{issueId}/cases": { summary: "Find the cases for a task",
description: "Accepts a task UUID or identifier and returns each readable case linked to that task, as { id, role, case: { id, identifier, ... } }. The top-level id is the link; pass case.id to read_case or the case audit history." },
"GET /api/cases/{id}": { summary: "Read a case and its current facts",
description: "Returns the case identifier, title, status, current facts (fields) and primary task." },
"PATCH /api/cases/{id}": { summary: "Update a case's facts, labels or status",
description: "Updates title, summary, fields, labels, project, parent case or status. For a case with a primary task, agents do not close it here: the agent assigned to that task records a terminal handoff to done, and only that agent may cancel or reopen the case." },
"GET /api/cases/{id}/events": { summary: "Read a case's audit history of fact changes, handoffs and links",
description: "Newest first. Each event has its kind (such as fields_changed, status_changed, issue_linked), the actor and time. An agent actor has actorAgentId and actorAgentName; a person has actorType user and actorUserId, without a display name. A fields_changed event records who changed the facts and when; it does not retain the previous fact values. Document edits are in document revisions and handoffs in the case handoff history." },
"GET /api/cases/{id}/documents/{key}/revisions": { summary: "Read a case document's revision history",
description: "Returns every revision of a case-owned document, newest first, with body, author and time. An agent author has actorAgentName; a person has createdByUserId, without a display name." },
"GET /api/companies/{companyId}/responsibilities": { summary: "List a person's responsibilities",
description: "Requires enableResponsibilities. Returns { ownerUserId, areas, responsibilities, proposed, totals, loose }: the company's active areas (plus any area a returned responsibility is under) with this person's active responsibilities counted by status, the person's active responsibilities (and let_go ones with includeLetGo=true), the ones still proposed, totals by status, and loose work under no responsibility. Each responsibility carries a rollup: health (on_track, at_risk, behind or not_measured, from the metric against its target), metric, statusSentence and workSummary signals from the projects, tasks and routines under it. Board users default to their own; agents default to the person their run works for, and must pass ownerUserId when the run works for no person." },
"POST /api/companies/{companyId}/responsibilities": { summary: "Create or propose a responsibility",
description: "Requires enableResponsibilities. Requires title, standard (the bar as a sentence) and metricName, plus the fields of the bar's template, metricKind: volume (metricTarget, optional metricDirection at_least or at_most and metricUnit), percentage (metricTarget 0-100, optional metricDirection; unit %), yes_no (no target: metricName is the statement that should be true) or range (metricLow and metricHigh, optional metricUnit). Without metricKind the bar is a percentage when metricUnit is %, otherwise a volume. metricCurrent (a number; true or false for yes_no), areaId and runByAgentId are optional. A board user creates an active responsibility for themselves. An agent acting for the person its run works for, when that person directed the run (their own chat or task, or their message woke it) and may manage the owner (their own, or anyone's for a company owner or admin), creates what that person could: a title alone is enough, it is active by default, and the change is saved as a version of the owner's Dashboard they can undo. Any other agent can only propose: it is saved with status proposed and source onboarding with the whole bar, and a board user confirms it. ownerUserId defaults to the person the run works for and must be a company member. Put why you propose it in evidence." },
"GET /api/responsibilities/{id}": { summary: "Read a responsibility with the work under it",
description: "Requires enableResponsibilities. Returns the responsibility, its rollup, its area, the linked projects, tasks (direct, or through a linked project) and routines, the skills held by the agents working under it, and the artifacts its tasks produced." },
"PATCH /api/responsibilities/{id}": { summary: "Update a responsibility or report its metric",
description: "Requires enableResponsibilities. An agent acting for the person its run works for, when that person directed the run (their own chat or task, or their message woke it) and may manage the owner, may change every field as that person could, saved as a version of the owner's Dashboard they can undo. Other agents may edit only responsibilities that are still proposed and may set status only to proposed or dismissed; confirming (active) or letting go is that person's decision. On an active responsibility an agent may send only { metricCurrent } (a number; true or false for a yes_no bar) and only when it runs the responsibility (runByAgentId) or is assigned a task or routine under it. Changing metricKind clears the inputs the new template does not use, and the reading unless metricCurrent is sent too; the merged bar must follow its template (422 otherwise). Setting status active needs standard, metricName and the template's inputs (metricTarget for volume and percentage, metricLow and metricHigh for range; 422 otherwise). healthOverride null clears a manual status override." },
"POST /api/responsibilities/{id}/file": { summary: "File items under a responsibility, optionally moving them",
description: "Requires enableResponsibilities. Body { items: [{ kind: project | task | routine, id }] (1-50), moveFrom?: a responsibility id, or all }. Files every item in one transaction; with moveFrom the items also leave that responsibility, or with all every other proposed or active responsibility of the same owner. A board user who manages the owner, or an agent acting for such a person (saved as an undoable Dashboard version). Returns { filed: [{ link, created }], unfiled: [link] }." },
"POST /api/responsibilities/{id}/unfile": { summary: "Unfile items from a responsibility by kind and id",
description: "Requires enableResponsibilities. Body { items: [{ kind: project | task | routine, id }] }. Removes only the links, with no link ids needed; items not filed here are skipped. Same writers as filing. Returns { unfiled: [link] }." },
"DELETE /api/responsibilities/{id}": { summary: "Delete a responsibility permanently",
description: "Requires enableResponsibilities. A board user who manages the owner. An agent acting for such a person must also send confirmationId: an accepted request_confirmation card it posted, with target { type: custom, key: responsibility-delete:<id> }, accepted by someone who may manage the owner (403 responsibility_delete_confirmation_required otherwise). Its links go with it; the items stay." },
"PATCH /api/responsibility-areas/{id}": { summary: "Rename, describe, reorder, archive or restore an area",
description: "Requires enableResponsibilities. A board user, or an agent acting for a member of the company (saved as a version of that person's Dashboard they can undo)." },
"DELETE /api/responsibility-areas/{id}": { summary: "Delete an area permanently",
description: "Requires enableResponsibilities. Its responsibilities move to moveResponsibilitiesTo (an area that is not archived) or are left with no area. A board user, or an agent acting for a member of the company with confirmationId: an accepted request_confirmation card it posted, with target { type: custom, key: responsibility-area-delete:<id> }. Returns the area and movedResponsibilities." },
"POST /api/responsibilities/{id}/links": { summary: "File a project, task, routine or skill under a responsibility",
description: "Requires enableResponsibilities. Send exactly one of projectId, issueId, routineId or skillId (a company skill the caller may see). An item can sit under several responsibilities; linking it here does not remove it from any other. Returns 201 for a new link and 200 when it was already linked here." },
"DELETE /api/responsibilities/{id}/links/{linkId}": { summary: "Remove an item from a responsibility",
description: "Requires enableResponsibilities. Removes only the link; the project, task or routine is unchanged." },
"POST /api/responsibilities/{id}/delegate": { summary: "Hand work under a responsibility to an agent",
description: "Requires enableResponsibilities. Board only. Creates a task assigned to assigneeAgentId, files it under the responsibility in the same transaction and wakes the agent. mode sets the opening instruction: plan_with_me, prepare_i_decide, handle_and_tell_me or own_from_now_on; own_from_now_on also makes the assignee the agent that runs the responsibility (runByAgentId). Returns { issue, link }." },
"GET /api/companies/{companyId}/responsibility-links/lookup": { summary: "Find the responsibilities a task, project or routine is under",
description: "Requires enableResponsibilities. Pass exactly one of issueId, projectId or routineId. Returns { responsibilities: [{ id, title, areaId, ownerUserId, via }] } for proposed and active responsibilities; via is direct, or project when a task or routine is under it through its project. Empty when the item is under none." },
"GET /api/companies/{companyId}/responsibilities/summary": { summary: "Read where a person's responsibilities stand, as a paragraph",
description: "Requires enableResponsibilities. Same access and ownerUserId rules as listing responsibilities. Returns { text, source, generatedAt, refreshing }: a short paragraph written to the owner about which active responsibilities are behind or at risk and why, what is going well and what needs attention next. source is model or computed (written by Paperclip from the same facts); refreshing true means newer model text is on its way, so ask again shortly." },
"GET /api/responsibilities/{id}/summary": { summary: "Read what is affecting a responsibility's number, as a paragraph",
description: "Requires enableResponsibilities. Same access as reading the responsibility. Returns { text, source, generatedAt, refreshing }: a short paragraph naming the projects, tasks and routines under it that are late, blocked, failing or unassigned, the ones moving, and whether the reading is stale. source is model or computed; refreshing true means newer model text is on its way." },
"GET /api/companies/{companyId}/responsibilities/automation": { summary: "Read how automated a person's responsibilities are",
description: "Requires enableResponsibilities. Same access and ownerUserId rules as listing responsibilities. Returns { ownerUserId, recentDays, responsibilities, areas, totals }. For each active responsibility: level (manual, some_automated, mostly_automated or automated), share (automations over automations plus manual tasks, 0-1, null with neither), automationCount, manualTaskCount, nothingFiled, automations (active routines with an agent, each with start: a schedule with its cadenceLabel and nextRunAt, a webhook with its webhookUrl and signingMode, a standing check with its lastResult, or on_request), stalledAutomations (paused, with no agent, or a standing check whose agent never wakes up on its own: no_wakeups), candidates (manual tasks most worth automating first, capped, each with reason, an instant hint { trigger: schedule | webhook | standing_check, words, cadence, why } or null, any pending agent offer, suggestedCadence, responsibleAgentId and any open automation conversation) and candidateTotal. Manual tasks are open or completed in the last recentDays days and exclude tasks a routine created, the onboarding task, bar and automation conversations and tasks already automated. areas and totals count each automation and task once." },
"GET /api/companies/{companyId}/responsibility-areas": { summary: "List responsibility areas",
description: "Requires enableResponsibilities. Areas are broad things the company cares about (Fundraising, Customers); they have no owner. Returns proposed and active areas, plus archived ones with includeArchived=true." },
"POST /api/companies/{companyId}/responsibility-areas": { summary: "Create or propose a responsibility area",
description: "Requires enableResponsibilities. A board user, or an agent acting for a member of the company, creates an active area (an agent's is saved as an undoable Dashboard version); any other agent's area is saved as proposed. If a non-archived area with the same title (case-insensitive) exists, returns it with 200 instead of creating another, so it is safe to call before filing a responsibility." },
"POST /api/issues/{id}/routine-suggestions": { summary: "Offer to repeat a finished task as a routine",
description: "Requires enableResponsibilities. Only the agent assigned to the task. Use it once, at the end of work that plausibly recurs (after marking the task done, or just before finish_task; an offer made before the task is done stays hidden until it is) (a weekly report, a daily check, a monthly reconciliation), never for one-off work. Send title (what repeats), instructions (what each run does, written out in full without {{placeholders}}), cadence { frequency: daily | weekdays | weekly | monthly, dayOfWeek for weekly (monday..sunday), dayOfMonth 1-28 for monthly, time HH:MM in the person's local time } and an optional one-sentence message to the person. The person sees the offer in the task conversation and accepts or declines; you are not woken either way. Returns 409 when the task already has an offer or was cancelled, and 422 for a task a routine created or the onboarding task." },
"POST /api/issues/{id}/routine-suggestions/{interactionId}/accept": { summary: "Accept a routine offer",
description: "Requires enableResponsibilities. Board only, with permission to assign tasks. Creates an active routine with the task's agent and project, scheduled at the offered cadence in timezone (defaults to the person's saved time zone, else UTC), files it under every responsibility the task is under, and returns { interaction, routine }." },
"POST /api/issues/{id}/routine-suggestions/{interactionId}/decline": { summary: "Decline a routine offer",
description: "Requires enableResponsibilities. Board only. Closes the offer; the task is not offered a routine again." },
"POST /api/issues/{id}/repeat-as-routine": { summary: "Turn a task into a routine",
description: "Requires enableResponsibilities. Board only, with permission to assign tasks. Send title, cadence { frequency: daily | weekdays | weekly | monthly, dayOfWeek for weekly, dayOfMonth 1-28 for monthly, time HH:MM }, assigneeAgentId and optional timezone (defaults to the person's saved time zone, else UTC). Creates an active routine with the task's project, scheduled at that cadence, records the task as its origin, files it under every responsibility the task is under, and settles the task's pending agent offer, if any, as accepted. The task itself is unchanged. Returns 201 { routine, cadenceLabel, timezone, responsibilityIds, acceptedOfferId }; 409 when a routine already repeats the task (routine_origin_exists) or the task was cancelled; 422 for a task a routine created, the onboarding task or a bar conversation." },
"GET /api/responsibilities/{id}/bar-conversation": { summary: "Read where a responsibility's bar conversation stands",
description: "Requires enableResponsibilities. Board only. Returns { responsibilityId, state (none, discussing, proposal_waiting or settled), defaultAgentId (null when no agent in the company can hold the conversation), conversation (the latest bar conversation task that was not cancelled), proposal (the pending proposal card, if any) }." },
"POST /api/responsibilities/{id}/bar-conversation": { summary: "Start a conversation with an agent about a responsibility's bar",
description: "Requires enableResponsibilities. Board only, for the owner or a company admin, with permission to assign tasks. Opens a task assigned to agentId (default: the agent that runs the responsibility, else the top of the org chart) whose conversation ends in a proposed bar, and wakes the agent. Returns 201 with the conversation state, or 200 with the existing one when a conversation is open or a proposal is waiting." },
"POST /api/issues/{id}/bar-proposals": { summary: "Propose a bar in a responsibility's bar conversation",
description: "Requires enableResponsibilities. Only the agent assigned to the bar conversation task. Send standard, metricKind (volume, percentage, yes_no or range; you choose), metricName and the template's inputs: metricTarget with optional metricDirection and metricUnit for volume, metricTarget 0-100 with optional metricDirection for percentage, no further inputs for yes_no, metricLow and metricHigh with optional metricUnit for range. Add metricCurrent (true or false for yes_no) only for a reading counted from real evidence, with currentEvidence saying how; add an optional one-sentence message. The responsibility stays as it is until a person accepts. A new proposal replaces the waiting one. 400 or 422 lists what is wrong with the bar; 409 means the conversation was cancelled or the responsibility closed." },
"POST /api/issues/{id}/bar-proposals/{interactionId}/accept": { summary: "Accept a proposed bar",
description: "Requires enableResponsibilities. Board only, for the responsibility's owner or a company admin. Applies the proposed bar (and its reading, if any) to the responsibility and settles the card in one transaction, and returns { interaction, responsibility }. Send keepMetrics (indexes into the proposal's supporting metrics) to apply only those and drop the rest; leave it out to apply them all. The bar's own metric is always applied, and the card's result lists droppedMetrics by title." },
"POST /api/issues/{id}/bar-proposals/{interactionId}/decline": { summary: "Say a proposed bar is not right",
description: "Requires enableResponsibilities. Board only, for the responsibility's owner or a company admin. Closes the card without changing the responsibility; the conversation continues and the agent can propose again." },
"GET /api/companies/{companyId}/responsibility-dashboard": { summary: "Read where a person's Dashboard conversation stands",
description: "Requires enableResponsibilities. Same access and ownerUserId rules as listing responsibilities. Returns { ownerUserId, empty (no active responsibility and none proposed), state (none, discussing, proposal_waiting or settled), defaultAgentId, conversation { issueId, identifier, mode create or edit, agentId, status }, proposal (the pending proposed changes, if any), latestChange (the newest version when it is applied changes or a restore from the last 24 hours, with previousVersionId for Undo) }." },
"GET /api/companies/{companyId}/responsibility-dashboard/versions": { summary: "List the saved versions of a person's Dashboard",
description: "Requires enableResponsibilities. Same access and ownerUserId rules as listing responsibilities. Returns { ownerUserId, versions }, newest first and at most 30, each { id, cause (change_set, person or restore), summary, actorUserId, actorAgentId, previousVersionId, restoredFromVersionId, createdAt }. When the caller may change this dashboard, the dashboard as it is now is saved first if it changed by hand since the newest version." },
"POST /api/companies/{companyId}/responsibility-dashboard/conversation": { summary: "Start a conversation with an agent about a person's Dashboard",
description: "Requires enableResponsibilities. Board only, for the person or a company admin. Send mode create (the agent interviews and researches the person, then drafts a first dashboard) or edit (the agent helps change it), optional ownerUserId (defaults to you) and agentId. Returns the open conversation when there is one (200), otherwise a new task assigned to the agent (201); a create conversation opens with the interview card. 422 when no agent can hold it." },
"POST /api/issues/{id}/dashboard-changes": { summary: "Propose changes to a person's Dashboard in their dashboard conversation",
description: "Requires enableResponsibilities. Only the agent assigned to the dashboard conversation task. Send { message (optional), changes }, an ordered list of: add_area { ref, name }, rename_area { areaId, name }, remove_area { areaId, reason }, add_responsibility { areaId or areaRef, sentence }, reword_responsibility { responsibilityId, sentence }, move_responsibility { responsibilityId, areaId or areaRef }, remove_responsibility { responsibilityId, reason }; each may carry a one-line reason, removals must. Nothing is applied: the person accepts the card, and may drop single changes first. A new proposal replaces the waiting one. 422 says what does not fit the dashboard; 409 when the conversation was cancelled." },
"POST /api/issues/{id}/dashboard-changes/{interactionId}/accept": { summary: "Apply proposed Dashboard changes",
description: "Requires enableResponsibilities. Board only, for the person or a company admin. Optional keep lists the changes to apply by index; a kept change may not depend on a dropped one (422). Applies them in one transaction: removed responsibilities are let go and removed areas archived, never deleted; new responsibilities are active with only their sentence. Saves a version before and after. Returns { interaction, version }." },
"POST /api/issues/{id}/dashboard-changes/{interactionId}/decline": { summary: "Say proposed Dashboard changes are not right",
description: "Requires enableResponsibilities. Board only, for the person or a company admin. Closes the card without changing anything; the conversation continues and the agent can propose again." },
"POST /api/responsibility-dashboard-versions/{id}/restore": { summary: "Restore a saved version of a person's Dashboard",
description: "Requires enableResponsibilities. Board only, for the person or a company admin. Puts back each area's and responsibility's name or sentence, area, order and status from the version; lets go of what the person owns now that it does not hold and archives an area left holding nothing of anyone's. Never deletes, and never touches bars, metrics, readings or what is filed under a responsibility. Saved as a new version, so it can be undone. Returns { version }." },
"GET /api/responsibilities/{id}/metrics": { summary: "Read a responsibility's metrics, ready to draw",
description: "Requires enableResponsibilities. Same access as reading the responsibility. Returns { responsibilityId, source, chosenBy, metrics, historyLimit }. metrics holds up to three, the primary first: the bar's own metric (role primary, its template in kind, its derived health), then supporting ones. Each has key, id (a supporting metric's id, for readings), title, description (how it is measured), display (number, percent, line or bar), unit, target, direction, latest and readings (oldest first, at most historyLimit), stale and note. source is chosen (an agent proposed the set in the bar conversation and the person accepted, or the owner set it) or starter (computed now from the work under it: tasks finished per week, open tasks, the share on routines; never stored, and each has starter set)." },
"PUT /api/responsibilities/{id}/metrics": { summary: "Set a responsibility's supporting metrics",
description: "Requires enableResponsibilities. Board only, for the owner or a company admin. Send metrics (at most two: title, description, display number | percent | line | bar, optional unit, target with direction at_least or at_most, readings [{ value, recordedAt }] and readingsEvidence) and optional primaryDisplay for the bar's own metric. Replaces the supporting metrics and returns the metric set. Agents propose a set in the bar conversation instead." },
"PATCH /api/responsibilities/{id}/metrics/{metricId}": { summary: "Change how one responsibility metric is drawn",
description: "Requires enableResponsibilities. Board only, for the owner or a company admin. metricId is a supporting metric's id, or primary for the bar's own metric. Send { display }: number, percent, line or bar, among the forms the metric's data allows (the bar's own follows its template: a range as number or line, a yes_no only as number; a supporting share as percent, line, bar or number; any other supporting metric as number, line or bar; 422 otherwise). Readings are unchanged. Returns the metric set." },
"DELETE /api/responsibilities/{id}/metrics/{metricId}": { summary: "Remove a supporting metric",
description: "Requires enableResponsibilities. Board only, for the owner or a company admin. Archives the supporting metric (its readings stay with it) and returns the metric set. The bar's own metric cannot be removed here." },
"POST /api/responsibilities/{id}/metrics/{metricId}/readings": { summary: "Record a reading of a responsibility metric",
description: "Requires enableResponsibilities. metricId is a supporting metric's id, or primary for the bar's own metric. Send value (a number; true or false for a yes_no bar) and an optional note. An agent may record on an active responsibility it runs or has a task or routine under, and only what is true now: recordedAt is refused. The owner (or a company admin) may also send recordedAt (a past time, for history) or readingId (to correct one). A primary reading becomes the bar's reading (status follows it) unless it is older than the one shown, when it joins the history only. Returns 201 { reading }." },
"GET /api/responsibilities/{id}/runs": { summary: "Read the recent agent runs on a responsibility's work",
description: "Requires enableResponsibilities. Same access as reading the responsibility. Returns { responsibilityId, runs, limit }: the most recent heartbeat runs on the tasks under it (filed directly or through a linked project) and on the tasks its routines created, newest first, at most limit (default 8, at most 20). Each run has id, agentId, status (queued, running, succeeded, failed, cancelled or timed_out), createdAt, startedAt, finishedAt, issue { id, identifier, title } (the task it ran on) and routineId when the task came from one of its routines. Only runs on tasks the caller can read are listed." },
"GET /api/issues/{id}/automation-conversation": { summary: "Read where a task's automation conversation stands",
description: "Requires enableResponsibilities. Board only. Returns { sourceIssueId, state (none, discussing, proposal_waiting or settled), defaultAgentId (the responsible agent, null when none can hold the conversation), conversation (the latest automation conversation task that was not cancelled), proposal (the pending proposal card, if any) }." },
"POST /api/issues/{id}/automation-conversation": { summary: "Start a conversation with an agent about automating a task",
description: "Requires enableResponsibilities. Board only, with permission to assign tasks. Opens a task assigned to agentId (default: the task's agent, else the agent that runs a responsibility it is under, starting with responsibilityId, else the organization's first assignable agent) whose description is the person's opening message with the instant hint and a link back, and wakes the agent. Returns 201 with the conversation state, or 200 with the existing one when a conversation is open or a proposal is waiting. 409 when the task is already automated or was cancelled; 422 for a task a routine created, the onboarding task or a bar or automation conversation." },
"POST /api/issues/{id}/automation-proposals": { summary: "Propose an automation in a task's automation conversation",
description: "Requires enableResponsibilities. Only the agent assigned to the automation conversation task. Send title (what is done each time), instructions (in full, without {{placeholders}}), trigger and an optional one-sentence message. trigger is { kind: schedule, cadence: { frequency: daily | weekdays | weekly | monthly, dayOfWeek for weekly, dayOfMonth 1-28 for monthly, time HH:MM } }, { kind: webhook, caller: in words, what calls it and when } or { kind: standing_check, lookFor, whenFound } (only for an agent whose heartbeat wakes it; 422 automation_standing_check_no_heartbeat otherwise). No automation exists until a person accepts. A new proposal replaces the waiting one. 409 means the conversation was cancelled or the task is already automated." },
"POST /api/issues/{id}/automation-proposals/{interactionId}/accept": { summary: "Accept a proposed automation",
description: "Requires enableResponsibilities. Board only, with permission to assign tasks. Creates an active routine run by the conversation's agent, in the task's project, recording the task as its origin, with a schedule (in timezone, default the person's saved time zone, else UTC), a webhook trigger (bearer secret) or a standing check (a heartbeat trigger that never fires a run), files it under every responsibility the task is under, and returns { interaction, routine, webhook }. webhook is { url, secret, signingMode } for a webhook only and is shown once: the secret is not stored on the card." },
"POST /api/issues/{id}/automation-proposals/{interactionId}/decline": { summary: "Say a proposed automation is not right",
description: "Requires enableResponsibilities. Board only. Closes the card without creating anything; the conversation continues and the agent can propose again." },
"GET /api/companies/{companyId}/responsibilities/status-reports": { summary: "Read the agent-written status of a person's responsibilities",
description: "Requires enableResponsibilities. Same access and ownerUserId rules as listing responsibilities. Returns { ownerUserId, freshDays, reports }: for each active responsibility, current (the newest report: status behind, at_risk, on_track or unknown, message, detail, agentId or userId of who wrote it, writtenAt and outOfDate when older than freshDays; null when none was written), reporterAgentId (the agent with the best total view of it: the agent doing the most under it, else the organization's top agent, else the first agent that can take work), reporterBasis (works_under, top_agent or first_agent) and updateRequested (the owner asked for an update and none has come since)." },
"GET /api/responsibilities/{id}/status-report": { summary: "Read a responsibility's agent-written status",
description: "Requires enableResponsibilities. Same access as reading the responsibility. Returns { current, reporterAgentId, updateRequested, history }: current is the newest report with outOfDate, or null; history lists recent reports newest first." },
"POST /api/responsibilities/{id}/status-report": { summary: "Write a responsibility's status",
description: "Requires enableResponsibilities. An agent may write it when it is the responsibility's reporter or works under it (runs it, has a task or routine under it, or leads a linked project); a person may write it when they may edit the responsibility. Send status (behind, at_risk, on_track, or unknown when you cannot tell yet), message (one plain line saying why, at most 200 characters, no markdown) and optional detail (a few sentences). The author is the caller; it cannot be named in the body. The responsibility must be active (409 otherwise). Returns 201 with the same body as reading it." },
"POST /api/responsibilities/{id}/status-report/request": { summary: "Ask the reporting agent for a status update",
description: "Requires enableResponsibilities. Board only, for the owner or a company admin, with permission to assign tasks. Opens a small task for the responsibility's reporter whose prompt carries the facts and the call, and wakes it; while one is open and unanswered, asking again changes nothing (200). Returns the same body as reading the status; 201 when a task was opened, 422 when no agent can take work." },
"POST /api/routines/{id}/standing-check-results": { summary: "Report what a standing check found",
description: "Requires enableResponsibilities. Only the agent that runs the standing check (the routine's agent). Send outcome (acted, or nothing_needed when the check found no work), note (one plain sentence; required when you acted) and the optional issueId of a task you created or updated. Recorded as a completed routine run with source heartbeat. 409 when the check is paused or removed." },
};
// Query contracts shared with the runtime parser where one exists.
export const experimentalApiQueries: Record<string, z.ZodObject<any>> = {
"GET /api/companies/{companyId}/cases": caseSchemas.listCasesQuerySchema,
"GET /api/cases/{id}/events": caseSchemas.listEventsQuerySchema,
"GET /api/cases/{id}": caseSchemas.caseDetailQuerySchema,
"PATCH /api/cases/{id}": caseSchemas.caseDetailQuerySchema,
"GET /api/companies/{companyId}/responsibilities": sharedSchemas.listResponsibilitiesQuerySchema,
"GET /api/companies/{companyId}/responsibility-areas": sharedSchemas.listResponsibilityAreasQuerySchema,
"DELETE /api/responsibilities/{id}": sharedSchemas.deleteResponsibilityQuerySchema,
"DELETE /api/responsibility-areas/{id}": sharedSchemas.deleteResponsibilityAreaQuerySchema,
"GET /api/companies/{companyId}/responsibilities/summary": sharedSchemas.listResponsibilitiesQuerySchema.pick({ ownerUserId: true }),
"GET /api/companies/{companyId}/responsibilities/automation": sharedSchemas.listResponsibilitiesQuerySchema.pick({ ownerUserId: true }),
"GET /api/companies/{companyId}/responsibilities/status-reports": sharedSchemas.listResponsibilitiesQuerySchema.pick({ ownerUserId: true }),
};