Files
PaperClipAI/packages/shared/src/constants.ts
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

1922 lines
61 KiB
TypeScript

export const COMPANY_STATUSES = ["active", "paused", "archived"] as const;
/**
* IDs per `/issues/summaries` request. Large enough that a typical recent-task
* list is one request; callers split longer lists into parallel chunks.
*/
export const ISSUE_SUMMARIES_MAX_IDS = 50;
/** Tasks per chat bootstrap request. The list preloads larger sets in chunks. */
export const ISSUE_CHAT_BOOTSTRAP_MAX_IDS = 10;
/** Tasks per keyed bulk document read; keeps a routine's case inventory in one request. */
export const ISSUE_DOCUMENT_BATCH_MAX_IDS = 200;
export type CompanyStatus = (typeof COMPANY_STATUSES)[number];
export const DEPLOYMENT_MODES = ["local_trusted", "authenticated"] as const;
export type DeploymentMode = (typeof DEPLOYMENT_MODES)[number];
export const DEPLOYMENT_EXPOSURES = ["private", "public"] as const;
export type DeploymentExposure = (typeof DEPLOYMENT_EXPOSURES)[number];
export const BIND_MODES = ["loopback", "lan", "tailnet", "custom"] as const;
export type BindMode = (typeof BIND_MODES)[number];
export const AUTH_BASE_URL_MODES = ["auto", "explicit"] as const;
export type AuthBaseUrlMode = (typeof AUTH_BASE_URL_MODES)[number];
export const AGENT_STATUSES = [
"active",
"paused",
"idle",
"running",
"error",
"pending_approval",
"terminated",
] as const;
export type AgentStatus = (typeof AGENT_STATUSES)[number];
export const AGENT_ADAPTER_TYPES = [
"process",
"http",
"claude_local",
"codex_local",
"paperclip_runner",
"cursor_cloud",
"gemini_local",
"grok_local",
"hermes_gateway",
"hermes_local",
"kimi_local",
"opencode_local",
"pi_local",
"cursor",
"openclaw_gateway",
] as const;
export type AgentAdapterType = (typeof AGENT_ADAPTER_TYPES)[number] | (string & {});
export const AGENT_ROLES = [
"ceo",
"cto",
"cmo",
"cfo",
"security",
"engineer",
"designer",
"pm",
"qa",
"devops",
"researcher",
"general",
] as const;
export type AgentRole = (typeof AGENT_ROLES)[number];
export const AGENT_ROLE_LABELS: Record<AgentRole, string> = {
ceo: "CEO",
cto: "CTO",
cmo: "CMO",
cfo: "CFO",
security: "Security",
engineer: "Engineer",
designer: "Designer",
pm: "PM",
qa: "QA",
devops: "DevOps",
researcher: "Researcher",
general: "General",
};
export const AGENT_DEFAULT_MAX_CONCURRENT_RUNS = 20;
export const WORKSPACE_BRANCH_ROUTINE_VARIABLE = "workspaceBranch";
// Config keys owned by Paperclip/company state rather than one concrete adapter.
// `paperclipSkillSync` is persisted in adapterConfig but must survive adapter swaps.
export const ADAPTER_AGNOSTIC_KEYS = [
"env",
"promptTemplate",
"instructionsFilePath",
"cwd",
"timeoutSec",
"graceSec",
"bootstrapPromptTemplate",
"paperclipSkillSync",
] as const;
export type AdapterAgnosticKey = (typeof ADAPTER_AGNOSTIC_KEYS)[number];
export const AGENT_ICON_NAMES = [
"bot",
"cpu",
"brain",
"zap",
"rocket",
"code",
"terminal",
"shield",
"eye",
"search",
"wrench",
"hammer",
"lightbulb",
"sparkles",
"star",
"heart",
"flame",
"bug",
"cog",
"database",
"globe",
"lock",
"mail",
"message-square",
"file-code",
"git-branch",
"package",
"puzzle",
"target",
"wand",
"atom",
"circuit-board",
"radar",
"swords",
"telescope",
"microscope",
"crown",
"gem",
"hexagon",
"pentagon",
"fingerprint",
] as const;
export type AgentIconName = (typeof AGENT_ICON_NAMES)[number];
/**
* Curated Lucide icon set for projects (PAP-68 part 3).
*
* The first entry, `"folder"`, is the default for any project without an
* explicit icon. The remaining entries reuse much of the agent icon set plus a
* handful of folder/structure icons that read well at small tile sizes.
*/
export const PROJECT_ICON_NAMES = [
"folder",
"rocket",
"code",
"terminal",
"database",
"globe",
"package",
"boxes",
"box",
"layers",
"briefcase",
"compass",
"target",
"flame",
"zap",
"star",
"bug",
"wrench",
"hammer",
"lightbulb",
"sparkles",
"shield",
"lock",
"search",
"cog",
"brain",
"cpu",
"git-branch",
"file-code",
"puzzle",
"gem",
"atom",
"heart",
"mail",
"message-square",
"crown",
"radar",
"telescope",
"hexagon",
] as const;
export type ProjectIconName = (typeof PROJECT_ICON_NAMES)[number];
export const ISSUE_STATUSES = [
"backlog",
"todo",
"in_progress",
"in_review",
"done",
"blocked",
"cancelled",
] as const;
export type IssueStatus = (typeof ISSUE_STATUSES)[number];
/** Read-only task presentation. Monitoring never grants execution authority. */
export const ISSUE_DISPLAY_STATUSES = [
"backlog", "todo", "in_progress", "monitoring", "in_review", "done", "blocked", "cancelled",
] as const;
export type IssueDisplayStatus = (typeof ISSUE_DISPLAY_STATUSES)[number];
export const INBOX_MINE_ISSUE_STATUSES = [
"backlog",
"todo",
"in_progress",
"in_review",
"blocked",
"done",
] as const;
export const INBOX_MINE_ISSUE_STATUS_FILTER = INBOX_MINE_ISSUE_STATUSES.join(",");
export const ISSUE_PRIORITIES = ["critical", "high", "medium", "low"] as const;
export type IssuePriority = (typeof ISSUE_PRIORITIES)[number];
export const ISSUE_REVIEW_POLICIES = ["anyone", "not_creator", "human_only"] as const;
export type IssueReviewPolicy = (typeof ISSUE_REVIEW_POLICIES)[number];
export const ISSUE_WORK_MODES = ["standard", "ask", "planning", "skill_test"] as const;
export type IssueWorkMode = (typeof ISSUE_WORK_MODES)[number];
export const ISSUE_HARNESS_KINDS = ["skill_test"] as const;
export type IssueHarnessKind = (typeof ISSUE_HARNESS_KINDS)[number];
export const MAX_ISSUE_REQUEST_DEPTH = 1024;
/**
* Deepest task tree an agent (or automation acting for one) may create: a root
* task plus one level of children. A deeper request is not rejected; the new
* task is parented at this depth instead, as a sibling of the requester. Board
* users are not limited, and existing deeper trees stay valid.
*/
export const MAX_AGENT_TASK_HIERARCHY_DEPTH = 2;
export const SUMMARY_SLOT_SCOPE_KINDS = [
"project",
"workspaces_overview",
"project_workspace",
"execution_workspace",
] as const;
export type SummarySlotScopeKind = (typeof SUMMARY_SLOT_SCOPE_KINDS)[number];
export const SUMMARY_SLOT_KEYS = ["header"] as const;
export type SummarySlotKey = (typeof SUMMARY_SLOT_KEYS)[number];
export const SUMMARY_SLOT_STATUSES = ["idle", "generating", "failed"] as const;
export type SummarySlotStatus = (typeof SUMMARY_SLOT_STATUSES)[number];
export const ISSUE_COMMENT_AUTHOR_TYPES = ["user", "agent", "system"] as const;
export type IssueCommentAuthorType = (typeof ISSUE_COMMENT_AUTHOR_TYPES)[number];
export const ISSUE_COMMENT_PRESENTATION_KINDS = ["message", "system_notice"] as const;
export type IssueCommentPresentationKind = (typeof ISSUE_COMMENT_PRESENTATION_KINDS)[number];
export const ISSUE_COMMENT_PRESENTATION_TONES = ["neutral", "info", "success", "warning", "danger"] as const;
export type IssueCommentPresentationTone = (typeof ISSUE_COMMENT_PRESENTATION_TONES)[number];
export const ISSUE_COMMENT_PRESENTATION_DENSITIES = ["compact"] as const;
export type IssueCommentPresentationDensity = (typeof ISSUE_COMMENT_PRESENTATION_DENSITIES)[number];
export const ISSUE_COMMENT_METADATA_ROW_TYPES = [
"text",
"code",
"key_value",
"issue_link",
"agent_link",
"run_link",
] as const;
export type IssueCommentMetadataRowType = (typeof ISSUE_COMMENT_METADATA_ROW_TYPES)[number];
export function clampIssueRequestDepth(value: number | null | undefined): number {
if (typeof value !== "number" || !Number.isFinite(value)) return 0;
return Math.min(MAX_ISSUE_REQUEST_DEPTH, Math.max(0, Math.floor(value)));
}
export const ISSUE_THREAD_INTERACTION_KINDS = [
"suggest_tasks",
"ask_user_questions",
"request_confirmation",
"request_checkbox_confirmation",
"request_item_verdicts",
"connection_intent",
// Server-authored offer to repeat a finished task as a routine
// (experimental `enableResponsibilities`). Not creatable through the generic
// interactions endpoint; see server/src/services/routine-suggestions.ts.
"suggest_routine",
// Server-authored bar an agent proposes in a responsibility's bar
// conversation (experimental `enableResponsibilities`). Not creatable through
// the generic interactions endpoint; see
// server/src/services/responsibility-bars.ts.
"propose_responsibility_bar",
// Server-authored automation an agent proposes in a task's automation
// conversation (experimental `enableResponsibilities`). Not creatable through
// the generic interactions endpoint; see
// server/src/services/responsibility-automation-conversations.ts.
"propose_automation",
// Server-authored change set an agent proposes for a person's Dashboard in
// their dashboard conversation (experimental `enableResponsibilities`). Not
// creatable through the generic interactions endpoint; see
// server/src/services/responsibility-dashboard.ts.
"propose_dashboard_changes",
] as const;
export type IssueThreadInteractionKind = (typeof ISSUE_THREAD_INTERACTION_KINDS)[number];
export const ISSUE_THREAD_INTERACTION_CANONICAL_RESOLVER_POLICIES = [
"anyone",
"not_creator",
"human_only",
] as const;
export type IssueThreadInteractionCanonicalResolverPolicy =
(typeof ISSUE_THREAD_INTERACTION_CANONICAL_RESOLVER_POLICIES)[number];
export const ISSUE_THREAD_INTERACTION_LEGACY_RESOLVER_POLICY_ALIASES = [
"board_or_agents",
"board_only",
] as const;
export type IssueThreadInteractionLegacyResolverPolicyAlias =
(typeof ISSUE_THREAD_INTERACTION_LEGACY_RESOLVER_POLICY_ALIASES)[number];
/**
* Accepted resolver-policy input values. New product surfaces should use the
* canonical values; the two board-prefixed values remain write-compatible
* aliases for one migration window.
*/
export const ISSUE_THREAD_INTERACTION_RESOLVER_POLICIES = [
...ISSUE_THREAD_INTERACTION_CANONICAL_RESOLVER_POLICIES,
...ISSUE_THREAD_INTERACTION_LEGACY_RESOLVER_POLICY_ALIASES,
] as const;
export type IssueThreadInteractionResolverPolicy =
(typeof ISSUE_THREAD_INTERACTION_RESOLVER_POLICIES)[number];
export const ISSUE_THREAD_INTERACTION_RESOLVER_POLICY_PROVENANCES = [
"explicit",
"inherited",
"legacy_inherited_restriction",
] as const;
export type IssueThreadInteractionResolverPolicyProvenance =
(typeof ISSUE_THREAD_INTERACTION_RESOLVER_POLICY_PROVENANCES)[number];
export const ISSUE_THREAD_INTERACTION_EFFECTIVE_RESOLVER_POLICY_SOURCES = [
"requested",
"company_cap",
"governed_action",
] as const;
export type IssueThreadInteractionEffectiveResolverPolicySource =
(typeof ISSUE_THREAD_INTERACTION_EFFECTIVE_RESOLVER_POLICY_SOURCES)[number];
export function normalizeIssueThreadInteractionResolverPolicy(
policy: IssueThreadInteractionResolverPolicy,
): IssueThreadInteractionCanonicalResolverPolicy {
if (policy === "board_or_agents") return "anyone";
if (policy === "board_only") return "human_only";
return policy;
}
export function legacyIssueThreadInteractionResolverPolicyAlias(
policy: IssueThreadInteractionCanonicalResolverPolicy,
): IssueThreadInteractionLegacyResolverPolicyAlias | null {
if (policy === "anyone") return "board_or_agents";
if (policy === "human_only") return "board_only";
return null;
}
export const REQUEST_CHECKBOX_CONFIRMATION_OPTION_LIMIT = 200;
export const REQUEST_ITEM_VERDICTS_ITEM_LIMIT = REQUEST_CHECKBOX_CONFIRMATION_OPTION_LIMIT;
export const ISSUE_THREAD_INTERACTION_STATUSES = [
"pending",
"accepted",
"rejected",
"answered",
"cancelled",
"expired",
"failed",
] as const;
export type IssueThreadInteractionStatus = (typeof ISSUE_THREAD_INTERACTION_STATUSES)[number];
export const ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES = [
"none",
"wake_assignee",
"wake_assignee_on_accept",
] as const;
export type IssueThreadInteractionContinuationPolicy =
(typeof ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES)[number];
export const TASK_WATCHDOG_PRODUCT_BUG_ORIGIN_KIND = "task_watchdog_product_bug";
// Marks the single onboarding "first task" so surfaces can special-case it
// (e.g. suppress the seeded-description bubble and rely on a seeded greeting).
export const ONBOARDING_FIRST_TASK_ORIGIN_KIND = "onboarding_first_task";
/**
* The task that holds a conversation with an agent about one responsibility's
* bar (experimental `enableResponsibilities`); its origin id is the
* responsibility id. See packages/shared/src/responsibility-bars.ts.
*/
export const RESPONSIBILITY_BAR_ORIGIN_KIND = "responsibility_bar";
/**
* The task that holds a conversation with an agent about turning one manual
* task into an automation (experimental `enableResponsibilities`); its origin
* id is that task's id. See packages/shared/src/responsibility-automation.ts.
*/
export const AUTOMATION_CONVERSATION_ORIGIN_KIND = "automation_conversation";
/**
* The small task asking the agent with the best view of one responsibility to
* write its status (experimental `enableResponsibilities`); its origin id is
* the responsibility id. See packages/shared/src/responsibility-status-reports.ts.
*/
export const RESPONSIBILITY_STATUS_UPDATE_ORIGIN_KIND = "responsibility_status_update";
/**
* The task that holds a conversation with an agent about one person's
* Dashboard: its areas and the responsibilities they own (experimental
* `enableResponsibilities`); its origin id is the person's user id and its
* origin fingerprint the mode (`create` or `edit`). See
* packages/shared/src/responsibility-dashboard.ts.
*/
export const RESPONSIBILITY_DASHBOARD_ORIGIN_KIND = "responsibility_dashboard";
export const ONBOARDING_CHAT_ORIGIN_KIND = "onboarding_chat";
export const ISSUE_ORIGIN_KINDS = [
"manual",
"routine_execution",
"stale_active_run_evaluation",
"harness_liveness_escalation",
// Historical origin only; automatic productivity reviews have been retired.
"issue_productivity_review",
"stranded_issue_recovery",
"task_watchdog",
TASK_WATCHDOG_PRODUCT_BUG_ORIGIN_KIND,
ONBOARDING_FIRST_TASK_ORIGIN_KIND,
ONBOARDING_CHAT_ORIGIN_KIND,
"chat_channel",
RESPONSIBILITY_BAR_ORIGIN_KIND,
AUTOMATION_CONVERSATION_ORIGIN_KIND,
RESPONSIBILITY_STATUS_UPDATE_ORIGIN_KIND,
RESPONSIBILITY_DASHBOARD_ORIGIN_KIND,
] as const;
export type BuiltInIssueOriginKind = (typeof ISSUE_ORIGIN_KINDS)[number];
export type PluginIssueOriginKind = `plugin:${string}`;
export type IssueOriginKind = BuiltInIssueOriginKind | PluginIssueOriginKind;
export const ISSUE_WATCHDOG_DISCOVERY_KINDS = ["product_bug", "platform_bug"] as const;
export type IssueWatchdogDiscoveryKind = (typeof ISSUE_WATCHDOG_DISCOVERY_KINDS)[number];
export const ISSUE_SURFACE_VISIBILITIES = ["default", "plugin_operation"] as const;
export type IssueSurfaceVisibility = (typeof ISSUE_SURFACE_VISIBILITIES)[number];
export const ISSUE_RECOVERY_ACTION_KINDS = [
"missing_disposition",
"deliberate_wait_without_target",
"stranded_assigned_issue",
"workspace_validation",
"configuration_validation",
"active_run_watchdog",
"issue_graph_liveness",
] as const;
export type IssueRecoveryActionKind = (typeof ISSUE_RECOVERY_ACTION_KINDS)[number];
export const ISSUE_DISPOSITION_REPAIR_RETRY_REASON = "issue_disposition_repair";
export const ISSUE_RECOVERY_ACTION_STATUSES = [
"active",
"escalated",
"resolved",
"cancelled",
] as const;
export type IssueRecoveryActionStatus = (typeof ISSUE_RECOVERY_ACTION_STATUSES)[number];
export const ISSUE_RECOVERY_ACTION_OWNER_TYPES = [
"agent",
"user",
"board",
"system",
] as const;
export type IssueRecoveryActionOwnerType = (typeof ISSUE_RECOVERY_ACTION_OWNER_TYPES)[number];
/**
* Wake reason for an agent whose child or blocker stalled on a recovery action
* that needs the board. Woken once per stall (one recovery action).
*/
export const ISSUE_BLOCKER_STALLED_WAKE_REASON = "issue_blocker_stalled" as const;
export const ISSUE_BLOCKER_STALL_RELATIONS = ["child", "blocker"] as const;
export type IssueBlockerStallRelation = (typeof ISSUE_BLOCKER_STALL_RELATIONS)[number];
export const ISSUE_RECOVERY_ACTION_OUTCOMES = [
"restored",
"handed_back",
"owner_completed",
"delegated",
"false_positive",
"blocked",
"escalated",
"cancelled",
] as const;
export type IssueRecoveryActionOutcome = (typeof ISSUE_RECOVERY_ACTION_OUTCOMES)[number];
export function pluginOperationIssueOriginKind(pluginKey: string): PluginIssueOriginKind {
return `plugin:${pluginKey}:operation`;
}
export function isPluginOperationIssueOriginKind(originKind: string | null | undefined): boolean {
return typeof originKind === "string" && /^plugin:[^:]+:operation(?::|$)/.test(originKind);
}
export const ISSUE_RELATION_TYPES = ["blocks"] as const;
export type IssueRelationType = (typeof ISSUE_RELATION_TYPES)[number];
export const ISSUE_TREE_CONTROL_MODES = ["pause", "resume", "cancel", "restore"] as const;
export type IssueTreeControlMode = (typeof ISSUE_TREE_CONTROL_MODES)[number];
export const ISSUE_TREE_HOLD_STATUSES = ["active", "released"] as const;
export type IssueTreeHoldStatus = (typeof ISSUE_TREE_HOLD_STATUSES)[number];
export const ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES = ["manual", "after_active_runs_finish"] as const;
export type IssueTreeHoldReleasePolicyStrategy = (typeof ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES)[number];
export const ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY = "continuation-summary" as const;
export const SYSTEM_ISSUE_DOCUMENT_KEYS = [
ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,
"pipeline-case-body",
] as const;
export type SystemIssueDocumentKey = (typeof SYSTEM_ISSUE_DOCUMENT_KEYS)[number];
const SYSTEM_ISSUE_DOCUMENT_KEY_SET = new Set<string>(SYSTEM_ISSUE_DOCUMENT_KEYS);
export function isSystemIssueDocumentKey(key: string): key is SystemIssueDocumentKey {
return SYSTEM_ISSUE_DOCUMENT_KEY_SET.has(key);
}
export const ISSUE_REFERENCE_SOURCE_KINDS = ["title", "description", "comment", "document"] as const;
export type IssueReferenceSourceKind = (typeof ISSUE_REFERENCE_SOURCE_KINDS)[number];
export const DOCUMENT_ANNOTATION_THREAD_STATUSES = ["open", "resolved"] as const;
export type DocumentAnnotationThreadStatus = (typeof DOCUMENT_ANNOTATION_THREAD_STATUSES)[number];
export const DOCUMENT_ANNOTATION_ANCHOR_STATES = ["active", "stale", "orphaned"] as const;
export type DocumentAnnotationAnchorState = (typeof DOCUMENT_ANNOTATION_ANCHOR_STATES)[number];
export const DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES = [
"exact",
"duplicate",
"fuzzy",
"ambiguous",
"missing",
] as const;
export type DocumentAnnotationAnchorConfidence =
(typeof DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES)[number];
export const EXTERNAL_OBJECT_STATUS_CATEGORIES = [
"unknown",
"open",
"waiting",
"running",
"succeeded",
"failed",
"blocked",
"closed",
"archived",
"auth_required",
"unreachable",
] as const;
export type ExternalObjectStatusCategory = (typeof EXTERNAL_OBJECT_STATUS_CATEGORIES)[number];
export const EXTERNAL_OBJECT_STATUS_TONES = [
"neutral",
"info",
"success",
"warning",
"danger",
"muted",
] as const;
export type ExternalObjectStatusTone = (typeof EXTERNAL_OBJECT_STATUS_TONES)[number];
export const EXTERNAL_OBJECT_LIVENESS_STATES = [
"unknown",
"fresh",
"stale",
"auth_required",
"rate_limited",
"unreachable",
] as const;
export type ExternalObjectLivenessState = (typeof EXTERNAL_OBJECT_LIVENESS_STATES)[number];
export const EXTERNAL_OBJECT_MENTION_SOURCE_KINDS = [
"title",
"description",
"comment",
"document",
"property",
"plugin",
] as const;
export type ExternalObjectMentionSourceKind = (typeof EXTERNAL_OBJECT_MENTION_SOURCE_KINDS)[number];
export const EXTERNAL_OBJECT_MENTION_CONFIDENCES = ["exact", "likely", "possible"] as const;
export type ExternalObjectMentionConfidence = (typeof EXTERNAL_OBJECT_MENTION_CONFIDENCES)[number];
export const ISSUE_EXECUTION_POLICY_MODES = ["normal", "auto"] as const;
export type IssueExecutionPolicyMode = (typeof ISSUE_EXECUTION_POLICY_MODES)[number];
export const ISSUE_EXECUTION_STAGE_TYPES = ["review", "approval"] as const;
export type IssueExecutionStageType = (typeof ISSUE_EXECUTION_STAGE_TYPES)[number];
export const ISSUE_MONITOR_SCHEDULED_BY = ["assignee", "board"] as const;
export type IssueMonitorScheduledBy = (typeof ISSUE_MONITOR_SCHEDULED_BY)[number];
export const ISSUE_EXECUTION_MONITOR_KINDS = ["external_service"] as const;
export type IssueExecutionMonitorKind = (typeof ISSUE_EXECUTION_MONITOR_KINDS)[number];
export const PROVIDER_QUOTA_MONITOR_SERVICE_NAME = "AI provider quota";
export const ISSUE_EXECUTION_MONITOR_RECOVERY_POLICIES = [
"wake_owner",
"create_recovery_issue",
"escalate_to_board",
] as const;
export type IssueExecutionMonitorRecoveryPolicy =
(typeof ISSUE_EXECUTION_MONITOR_RECOVERY_POLICIES)[number];
export const ISSUE_EXECUTION_STATE_STATUSES = ["idle", "pending", "changes_requested", "completed"] as const;
export type IssueExecutionStateStatus = (typeof ISSUE_EXECUTION_STATE_STATUSES)[number];
export const ISSUE_EXECUTION_MONITOR_STATE_STATUSES = ["scheduled", "triggered", "cleared"] as const;
export type IssueExecutionMonitorStateStatus = (typeof ISSUE_EXECUTION_MONITOR_STATE_STATUSES)[number];
export const ISSUE_EXECUTION_MONITOR_CLEAR_REASONS = [
"manual",
"triggered",
"done",
"cancelled",
"invalid_status",
"invalid_assignee",
"dispatch_skipped",
"timeout_exceeded",
"max_attempts_exhausted",
] as const;
export type IssueExecutionMonitorClearReason = (typeof ISSUE_EXECUTION_MONITOR_CLEAR_REASONS)[number];
export const ISSUE_EXECUTION_DECISION_OUTCOMES = ["approved", "changes_requested"] as const;
export type IssueExecutionDecisionOutcome = (typeof ISSUE_EXECUTION_DECISION_OUTCOMES)[number];
export const GOAL_LEVELS = ["company", "team", "agent", "task"] as const;
export type GoalLevel = (typeof GOAL_LEVELS)[number];
export const GOAL_STATUSES = ["planned", "active", "achieved", "cancelled"] as const;
export type GoalStatus = (typeof GOAL_STATUSES)[number];
export const PROJECT_STATUSES = [
"backlog",
"planned",
"in_progress",
"completed",
"cancelled",
] as const;
export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
/** Responsibilities (experimental, `enableResponsibilities`). */
export const RESPONSIBILITY_STATUSES = ["proposed", "active", "let_go", "dismissed"] as const;
export type ResponsibilityStatus = (typeof RESPONSIBILITY_STATUSES)[number];
export const RESPONSIBILITY_SOURCES = ["manual", "onboarding"] as const;
export type ResponsibilitySource = (typeof RESPONSIBILITY_SOURCES)[number];
/**
* Status of a responsibility, derived from its metric against its target.
* `not_measured`: no metric name, no target, or no current reading yet.
* Work under the responsibility does not change it (see the work summary).
*/
export const RESPONSIBILITY_HEALTH = ["behind", "at_risk", "on_track", "not_measured"] as const;
export type ResponsibilityHealth = (typeof RESPONSIBILITY_HEALTH)[number];
/** The values a person may set as a manual status override. */
export const RESPONSIBILITY_HEALTH_OVERRIDES = ["behind", "at_risk", "on_track"] as const;
export type ResponsibilityHealthOverride = (typeof RESPONSIBILITY_HEALTH_OVERRIDES)[number];
/** `at_least`: higher is better (attainment = current / target). `at_most`: lower is better (target / current). */
export const RESPONSIBILITY_METRIC_DIRECTIONS = ["at_least", "at_most"] as const;
export type ResponsibilityMetricDirection = (typeof RESPONSIBILITY_METRIC_DIRECTIONS)[number];
/** Attainment at or above 1 is on track; at or above this (and below 1) is at risk; below it is behind. */
export const RESPONSIBILITY_AT_RISK_THRESHOLD = 0.75;
/** A current reading older than this many days is reported as stale. */
export const RESPONSIBILITY_METRIC_STALE_DAYS = 14;
/** An unfinished project whose target date is within this many days is "due soon". */
export const RESPONSIBILITY_DUE_SOON_DAYS = 7;
/** Tasks completed within this many days count as "recently completed". */
export const RESPONSIBILITY_RECENTLY_COMPLETED_DAYS = 7;
/** Per-item work-summary signals (one per project, task or routine) beyond this many collapse into one "more" line. */
export const RESPONSIBILITY_WORK_SIGNAL_ITEM_LIMIT = 5;
/** Most artifacts listed in a responsibility detail, newest first. */
export const RESPONSIBILITY_DETAIL_ARTIFACT_LIMIT = 50;
/** `artifactsTotal` in a responsibility detail counts up to this many, then stops. */
export const RESPONSIBILITY_ARTIFACT_COUNT_LIMIT = 1000;
/** Most loose tasks listed in the overview; `loose.openTaskCount` is always complete. */
export const RESPONSIBILITY_LOOSE_TASK_LIMIT = 50;
/** Most loose projects and routines listed in the overview; their counts are always complete. */
export const RESPONSIBILITY_LOOSE_LIST_LIMIT = 100;
/** Work-summary signal kinds, in the order the summary lists them within a tone. */
export const RESPONSIBILITY_WORK_SIGNAL_KINDS = [
"metric_stale",
"project_late",
"routine_failed",
"task_blocked",
"project_due_soon",
"routine_paused",
"tasks_open_agent",
"tasks_open_person",
"tasks_open_unassigned",
"tasks_completed_recently",
"routine_active",
] as const;
export type ResponsibilityWorkSignalKind = (typeof RESPONSIBILITY_WORK_SIGNAL_KINDS)[number];
/** Signal tones, in summary order: what needs attention first. */
export const RESPONSIBILITY_WORK_SIGNAL_TONES = ["attention", "neutral", "good"] as const;
export type ResponsibilityWorkSignalTone = (typeof RESPONSIBILITY_WORK_SIGNAL_TONES)[number];
/** Responsibility areas: broad nouns a company cares about, with no owner. */
export const RESPONSIBILITY_AREA_STATUSES = ["proposed", "active", "archived"] as const;
export type ResponsibilityAreaStatus = (typeof RESPONSIBILITY_AREA_STATUSES)[number];
export const RESPONSIBILITY_AREA_SOURCES = ["manual", "onboarding"] as const;
export type ResponsibilityAreaSource = (typeof RESPONSIBILITY_AREA_SOURCES)[number];
export const RESPONSIBILITY_DELEGATION_MODES = [
"plan_with_me",
"prepare_i_decide",
"handle_and_tell_me",
"own_from_now_on",
] as const;
export type ResponsibilityDelegationMode = (typeof RESPONSIBILITY_DELEGATION_MODES)[number];
/** Most member tasks listed in a responsibility detail; rollup counts are not limited. */
export const RESPONSIBILITY_DETAIL_TASK_LIMIT = 200;
export const ENVIRONMENT_DRIVERS = ["local", "ssh", "sandbox", "plugin"] as const;
export type EnvironmentDriver = (typeof ENVIRONMENT_DRIVERS)[number];
export const ENVIRONMENT_STATUSES = ["active", "archived"] as const;
export type EnvironmentStatus = (typeof ENVIRONMENT_STATUSES)[number];
export const ENVIRONMENT_LEASE_STATUSES = ["active", "released", "expired", "failed", "retained", "pending_cleanup"] as const;
export type EnvironmentLeaseStatus = (typeof ENVIRONMENT_LEASE_STATUSES)[number];
export const ENVIRONMENT_LEASE_POLICIES = [
"ephemeral",
"reuse_by_environment",
"reuse_by_execution_workspace",
"retain_on_failure",
] as const;
export type EnvironmentLeasePolicy = (typeof ENVIRONMENT_LEASE_POLICIES)[number];
export const ENVIRONMENT_LEASE_CLEANUP_STATUSES = ["pending", "success", "failed"] as const;
export type EnvironmentLeaseCleanupStatus = (typeof ENVIRONMENT_LEASE_CLEANUP_STATUSES)[number];
export const ENVIRONMENT_CUSTOM_IMAGE_TEMPLATE_KINDS = [
"snapshot",
"image",
"provider_template",
"unknown",
] as const;
export type EnvironmentCustomImageTemplateKind = (typeof ENVIRONMENT_CUSTOM_IMAGE_TEMPLATE_KINDS)[number];
export const ENVIRONMENT_CUSTOM_IMAGE_TEMPLATE_STATUSES = [
"active",
"superseded",
"revoked",
"failed",
] as const;
export type EnvironmentCustomImageTemplateStatus = (typeof ENVIRONMENT_CUSTOM_IMAGE_TEMPLATE_STATUSES)[number];
export const ENVIRONMENT_CUSTOM_IMAGE_SETUP_SESSION_STATUSES = [
"starting",
"waiting_for_user",
"capturing",
"promoted",
"cancelled",
"timed_out",
"failed",
] as const;
export type EnvironmentCustomImageSetupSessionStatus =
(typeof ENVIRONMENT_CUSTOM_IMAGE_SETUP_SESSION_STATUSES)[number];
export const ENVIRONMENT_CUSTOM_IMAGE_SETUP_CONNECTION_TYPES = [
"ssh",
"browser_terminal",
"unknown",
] as const;
export type EnvironmentCustomImageSetupConnectionType =
(typeof ENVIRONMENT_CUSTOM_IMAGE_SETUP_CONNECTION_TYPES)[number];
export const ROUTINE_STATUSES = ["active", "paused", "archived"] as const;
export type RoutineStatus = (typeof ROUTINE_STATUSES)[number];
export const ROUTINE_CONCURRENCY_POLICIES = ["coalesce_if_active", "always_enqueue", "skip_if_active"] as const;
export type RoutineConcurrencyPolicy = (typeof ROUTINE_CONCURRENCY_POLICIES)[number];
export const ROUTINE_CATCH_UP_POLICIES = ["skip_missed", "enqueue_missed_with_cap"] as const;
export type RoutineCatchUpPolicy = (typeof ROUTINE_CATCH_UP_POLICIES)[number];
export const ROUTINE_ACTIVITY_GATE_POLICIES = ["always", "require_external_activity"] as const;
export type RoutineActivityGatePolicy = (typeof ROUTINE_ACTIVITY_GATE_POLICIES)[number];
export const ROUTINE_ACTIVITY_GATE_SCOPES = ["company", "project"] as const;
export type RoutineActivityGateScope = (typeof ROUTINE_ACTIVITY_GATE_SCOPES)[number];
/**
* `heartbeat` is a standing check (experimental `enableResponsibilities`): it
* never fires a run by itself. Instead the routine's agent carries out the
* routine's instructions each time its heartbeat timer wakes it, and reports
* the outcome. See server/src/services/routine-standing-checks.ts.
*/
export const ROUTINE_TRIGGER_KINDS = ["schedule", "webhook", "api", "heartbeat"] as const;
export type RoutineTriggerKind = (typeof ROUTINE_TRIGGER_KINDS)[number];
export const ROUTINE_TRIGGER_SIGNING_MODES = ["bearer", "app_webhook", "hmac_sha256", "github_hmac", "fireflies_hmac", "none"] as const;
export type RoutineTriggerSigningMode = (typeof ROUTINE_TRIGGER_SIGNING_MODES)[number];
export const ROUTINE_VARIABLE_TYPES = ["text", "textarea", "number", "boolean", "select", "date"] as const;
export type RoutineVariableType = (typeof ROUTINE_VARIABLE_TYPES)[number];
export const ROUTINE_RUN_STATUSES = [
"received",
"coalesced",
"skipped",
"issue_created",
"completed",
"failed",
] as const;
export type RoutineRunStatus = (typeof ROUTINE_RUN_STATUSES)[number];
/** `heartbeat`: a standing check's reported outcome (no task is created per check). */
export const ROUTINE_RUN_SOURCES = ["schedule", "manual", "api", "webhook", "heartbeat"] as const;
export type RoutineRunSource = (typeof ROUTINE_RUN_SOURCES)[number];
// "import" marks agents parked by a company import (safety default) so the UI
// can explain the pause and offer a scoped bulk-resume; "system" remains the
// reason for platform-managed pauses (plugins, built-ins).
export const PAUSE_REASONS = ["manual", "budget", "system", "company_archived", "import", "setup"] as const;
export type PauseReason = (typeof PAUSE_REASONS)[number];
export const PROJECT_COLORS = [
"#6366f1", // indigo
"#8b5cf6", // violet
"#ec4899", // pink
"#ef4444", // red
"#f97316", // orange
"#eab308", // yellow
"#22c55e", // green
"#14b8a6", // teal
"#06b6d4", // cyan
"#3b82f6", // blue
] as const;
export const APPROVAL_TYPES = [
"hire_agent",
"approve_ceo_strategy",
"budget_override_required",
"request_board_approval",
] as const;
export type ApprovalType = (typeof APPROVAL_TYPES)[number];
export const APPROVAL_STATUSES = [
"pending",
"revision_requested",
"approved",
"rejected",
"cancelled",
] as const;
export type ApprovalStatus = (typeof APPROVAL_STATUSES)[number];
export const SECRET_PROVIDERS = [
"local_encrypted",
"aws_secrets_manager",
"gcp_secret_manager",
"vault",
] as const;
export type SecretProvider = (typeof SECRET_PROVIDERS)[number];
export const SECRET_PROVIDER_CONFIG_STATUSES = [
"ready",
"warning",
"coming_soon",
"disabled",
] as const;
export type SecretProviderConfigStatus = (typeof SECRET_PROVIDER_CONFIG_STATUSES)[number];
export const SECRET_PROVIDER_CONFIG_HEALTH_STATUSES = [
"ready",
"warning",
"error",
"coming_soon",
"disabled",
] as const;
export type SecretProviderConfigHealthStatus =
(typeof SECRET_PROVIDER_CONFIG_HEALTH_STATUSES)[number];
export const SECRET_STATUSES = ["active", "disabled", "archived", "deleted"] as const;
export type SecretStatus = (typeof SECRET_STATUSES)[number];
export const SECRET_SCOPES = ["company", "user", "instance"] as const;
export type SecretScope = (typeof SECRET_SCOPES)[number];
export const SECRET_MANAGED_MODES = ["paperclip_managed", "external_reference"] as const;
export type SecretManagedMode = (typeof SECRET_MANAGED_MODES)[number];
export const SECRET_VERSION_STATUSES = [
"current",
"previous",
"disabled",
"destroyed",
"failed",
] as const;
export type SecretVersionStatus = (typeof SECRET_VERSION_STATUSES)[number];
export const SECRET_BINDING_TARGET_TYPES = [
"agent",
"project",
"environment",
"routine",
"plugin",
"issue",
"run",
"tool_connection",
"system",
] as const;
export type SecretBindingTargetType = (typeof SECRET_BINDING_TARGET_TYPES)[number];
export const SECRET_ACCESS_OUTCOMES = [
"success",
"failure",
"missing",
"inactive",
"not_allowed",
"optional_omitted",
"provider_error",
] as const;
export type SecretAccessOutcome = (typeof SECRET_ACCESS_OUTCOMES)[number];
export const SECRET_PROJECTION_CLASSES = ["unclassified", "class_3_static_lease"] as const;
export type SecretProjectionClass = (typeof SECRET_PROJECTION_CLASSES)[number];
export const CLASS3_STATIC_LEASE_ALLOWLIST = [
{
key: "slack.bot_token",
label: "Slack bot token",
targetType: "agent",
configPath: "env.SLACK_BOT_TOKEN",
envKey: "SLACK_BOT_TOKEN",
},
{
key: "slack.bot_token",
label: "Slack bot token",
targetType: "routine",
configPath: "env.SLACK_BOT_TOKEN",
envKey: "SLACK_BOT_TOKEN",
},
{
key: "slack.bot_token",
label: "Slack bot token governance connection",
targetType: "tool_connection",
configPath: "credentials.bot_token",
envKey: "SLACK_BOT_TOKEN",
},
{
key: "discord.bot_token",
label: "Discord bot token",
targetType: "agent",
configPath: "env.DISCORD_BOT_TOKEN",
envKey: "DISCORD_BOT_TOKEN",
},
{
key: "discord.bot_token",
label: "Discord bot token",
targetType: "routine",
configPath: "env.DISCORD_BOT_TOKEN",
envKey: "DISCORD_BOT_TOKEN",
},
{
key: "discord.bot_token",
label: "Discord bot token governance connection",
targetType: "tool_connection",
configPath: "credentials.bot_token",
envKey: "DISCORD_BOT_TOKEN",
},
] as const;
export type Class3StaticLeaseAllowlistKey = (typeof CLASS3_STATIC_LEASE_ALLOWLIST)[number]["key"];
export const STORAGE_PROVIDERS = ["local_disk", "s3"] as const;
export type StorageProvider = (typeof STORAGE_PROVIDERS)[number];
export const BILLING_TYPES = [
"metered_api",
"subscription_included",
"subscription_overage",
"credits",
"fixed",
"unknown",
] as const;
export type BillingType = (typeof BILLING_TYPES)[number];
export const COST_STATUSES = ["reported", "estimated", "unpriced"] as const;
export type CostStatus = (typeof COST_STATUSES)[number];
export const FINANCE_EVENT_KINDS = [
"inference_charge",
"platform_fee",
"credit_purchase",
"credit_refund",
"credit_expiry",
"byok_fee",
"gateway_overhead",
"log_storage_charge",
"logpush_charge",
"provisioned_capacity_charge",
"training_charge",
"custom_model_import_charge",
"custom_model_storage_charge",
"manual_adjustment",
] as const;
export type FinanceEventKind = (typeof FINANCE_EVENT_KINDS)[number];
export const FINANCE_DIRECTIONS = ["debit", "credit"] as const;
export type FinanceDirection = (typeof FINANCE_DIRECTIONS)[number];
export const FINANCE_UNITS = [
"input_token",
"output_token",
"cached_input_token",
"request",
"credit_usd",
"credit_unit",
"model_unit_minute",
"model_unit_hour",
"gb_month",
"train_token",
"unknown",
] as const;
export type FinanceUnit = (typeof FINANCE_UNITS)[number];
export const BUDGET_SCOPE_TYPES = ["company", "agent", "project"] as const;
export type BudgetScopeType = (typeof BUDGET_SCOPE_TYPES)[number];
export const BUDGET_METRICS = ["billed_cents"] as const;
export type BudgetMetric = (typeof BUDGET_METRICS)[number];
export const BUDGET_WINDOW_KINDS = ["calendar_month_utc", "lifetime"] as const;
export type BudgetWindowKind = (typeof BUDGET_WINDOW_KINDS)[number];
export const BUDGET_THRESHOLD_TYPES = ["soft", "hard"] as const;
export type BudgetThresholdType = (typeof BUDGET_THRESHOLD_TYPES)[number];
export const BUDGET_INCIDENT_STATUSES = ["open", "resolved", "dismissed"] as const;
export type BudgetIncidentStatus = (typeof BUDGET_INCIDENT_STATUSES)[number];
export const BUDGET_INCIDENT_RESOLUTION_ACTIONS = [
"keep_paused",
"raise_budget_and_resume",
] as const;
export type BudgetIncidentResolutionAction = (typeof BUDGET_INCIDENT_RESOLUTION_ACTIONS)[number];
export const HEARTBEAT_INVOCATION_SOURCES = [
"timer",
"assignment",
"on_demand",
"automation",
] as const;
export type HeartbeatInvocationSource = (typeof HEARTBEAT_INVOCATION_SOURCES)[number];
export const WAKEUP_TRIGGER_DETAILS = ["manual", "ping", "callback", "system"] as const;
export type WakeupTriggerDetail = (typeof WAKEUP_TRIGGER_DETAILS)[number];
export const WAKEUP_REQUEST_STATUSES = [
"queued",
"deferred_issue_execution",
"claimed",
"coalesced",
"skipped",
"completed",
"failed",
"cancelled",
] as const;
export type WakeupRequestStatus = (typeof WAKEUP_REQUEST_STATUSES)[number];
export const HEARTBEAT_RUN_STATUSES = [
"queued",
"scheduled_retry",
"running",
"succeeded",
"interrupted",
"failed",
"cancelled",
"timed_out",
] as const;
export type HeartbeatRunStatus = (typeof HEARTBEAT_RUN_STATUSES)[number];
export const RUN_LIVENESS_STATES = [
"completed",
"advanced",
"plan_only",
"empty_response",
"blocked",
"failed",
"needs_followup",
] as const;
export type RunLivenessState = (typeof RUN_LIVENESS_STATES)[number];
export const LIVE_EVENT_TYPES = [
"heartbeat.run.queued",
"heartbeat.run.status",
"heartbeat.run.progress",
"heartbeat.run.event",
"heartbeat.run.log",
"heartbeat.run.activity",
"heartbeat.run.tool_progress",
"agent.session.goal.changed",
"agent.status",
"agent.runtime_state.updated",
"activity.logged",
"external_object.updated",
"plugin.ui.updated",
"plugin.worker.crashed",
"plugin.worker.restarted",
] as const;
export type LiveEventType = (typeof LIVE_EVENT_TYPES)[number];
export const PRINCIPAL_TYPES = ["user", "agent"] as const;
export type PrincipalType = (typeof PRINCIPAL_TYPES)[number];
export const MEMBERSHIP_STATUSES = ["pending", "active", "suspended", "archived"] as const;
export type MembershipStatus = (typeof MEMBERSHIP_STATUSES)[number];
export const COMPANY_MEMBERSHIP_ROLES = [
"owner",
"admin",
"operator",
"viewer",
"member",
] as const;
export type CompanyMembershipRole = (typeof COMPANY_MEMBERSHIP_ROLES)[number];
export const HUMAN_COMPANY_MEMBERSHIP_ROLES = [
"owner",
"admin",
"operator",
"viewer",
] as const;
export type HumanCompanyMembershipRole = (typeof HUMAN_COMPANY_MEMBERSHIP_ROLES)[number];
export const HUMAN_COMPANY_MEMBERSHIP_ROLE_LABELS: Record<HumanCompanyMembershipRole, string> = {
owner: "Owner",
admin: "Admin",
operator: "Operator",
viewer: "Viewer",
};
export const INSTANCE_USER_ROLES = ["instance_admin"] as const;
export type InstanceUserRole = (typeof INSTANCE_USER_ROLES)[number];
export const INVITE_TYPES = ["company_join", "bootstrap_ceo"] as const;
export type InviteType = (typeof INVITE_TYPES)[number];
export const INVITE_JOIN_TYPES = ["human", "agent", "both"] as const;
export type InviteJoinType = (typeof INVITE_JOIN_TYPES)[number];
export const JOIN_REQUEST_TYPES = ["human", "agent"] as const;
export type JoinRequestType = (typeof JOIN_REQUEST_TYPES)[number];
export const JOIN_REQUEST_STATUSES = ["pending_approval", "approved", "rejected"] as const;
export type JoinRequestStatus = (typeof JOIN_REQUEST_STATUSES)[number];
export const PERMISSION_KEYS = [
"agents:create",
"agents:read",
"agents:configure",
"agents:suggest-changes",
"skills:create",
"skills:suggest-changes",
"environments:manage",
"tools:admin",
"tools:manage_connections",
"tools:manage_profiles",
"tools:view_audit",
"audit:view_agent_actions",
"commentary:view",
"tools:use",
"tools:manage_runtime",
"inbox:manage",
"users:invite",
"users:manage_permissions",
"tasks:assign",
"tasks:assign_scope",
"tasks:manage_active_checkouts",
"joins:approve",
] as const;
export type PermissionKey = (typeof PERMISSION_KEYS)[number];
export const TOOL_APPLICATION_TYPES = ["rest_api", "mcp_http", "mcp_stdio", "paperclip_plugin", "a2a", "chat"] as const;
export type ToolApplicationType = (typeof TOOL_APPLICATION_TYPES)[number];
export const TOOL_APPLICATION_STATUSES = ["draft", "active", "disabled", "archived"] as const;
export type ToolApplicationStatus = (typeof TOOL_APPLICATION_STATUSES)[number];
export const TOOL_CONNECTION_KINDS = ["managed"] as const;
export type ToolConnectionKind = (typeof TOOL_CONNECTION_KINDS)[number];
export const TOOL_CONNECTION_HEALTH_STATUSES = [
"unknown",
"healthy",
"degraded",
"failed",
"unchecked",
"ok",
"error",
"missing_secret",
] as const;
export type ToolConnectionHealthStatus = (typeof TOOL_CONNECTION_HEALTH_STATUSES)[number];
/**
* Health states that mean an app needs the user's attention (a bad/missing key
* or a degraded connection). Single source of truth shared by the needs-
* attention aggregation and the prosumer Apps surfaces so their counts agree.
*/
export const TOOL_CONNECTION_ATTENTION_HEALTH_STATUSES: readonly ToolConnectionHealthStatus[] = [
"degraded",
"failed",
"error",
"missing_secret",
];
export function isToolConnectionAttentionHealth(status: ToolConnectionHealthStatus): boolean {
return TOOL_CONNECTION_ATTENTION_HEALTH_STATUSES.includes(status);
}
export const TOOL_CATALOG_ENTRY_KINDS = ["tool", "resource", "prompt"] as const;
export type ToolCatalogEntryKind = (typeof TOOL_CATALOG_ENTRY_KINDS)[number];
export const TOOL_CATALOG_ENTRY_STATUSES = ["active", "disabled", "quarantined", "removed"] as const;
export type ToolCatalogEntryStatus = (typeof TOOL_CATALOG_ENTRY_STATUSES)[number];
export const TOOL_RISK_LEVELS = ["low", "medium", "high", "critical", "read", "write", "destructive"] as const;
export type ToolRiskLevel = (typeof TOOL_RISK_LEVELS)[number];
export const TOOL_PROFILE_STATUSES = ["draft", "active", "disabled", "archived"] as const;
export type ToolProfileStatus = (typeof TOOL_PROFILE_STATUSES)[number];
export const TOOL_PROFILE_DEFAULT_ACTIONS = ["deny", "allow"] as const;
export type ToolProfileDefaultAction = (typeof TOOL_PROFILE_DEFAULT_ACTIONS)[number];
export const TOOL_PROFILE_ENTRY_SELECTOR_TYPES = [
"application",
"connection",
"catalog_entry",
"tool_name",
"risk_level",
] as const;
export type ToolProfileEntrySelectorType = (typeof TOOL_PROFILE_ENTRY_SELECTOR_TYPES)[number];
export const TOOL_PROFILE_ENTRY_EFFECTS = ["include", "exclude"] as const;
export type ToolProfileEntryEffect = (typeof TOOL_PROFILE_ENTRY_EFFECTS)[number];
export const TOOL_PROFILE_BINDING_TARGET_TYPES = ["company", "agent", "project", "routine", "issue", "gateway"] as const;
export type ToolProfileBindingTargetType = (typeof TOOL_PROFILE_BINDING_TARGET_TYPES)[number];
export const TOOL_MCP_GATEWAY_STATUSES = ["draft", "active", "disabled", "archived"] as const;
export type ToolMcpGatewayStatus = (typeof TOOL_MCP_GATEWAY_STATUSES)[number];
export const TOOL_MCP_GATEWAY_DEFAULT_PROFILE_MODES = [
"gateway_only",
"inherit_context_then_gateway",
"gateway_then_context",
] as const;
export type ToolMcpGatewayDefaultProfileMode = (typeof TOOL_MCP_GATEWAY_DEFAULT_PROFILE_MODES)[number];
export const TOOL_MCP_GATEWAY_CONTEXT_SCOPE_TYPES = [
"none",
"company",
"project",
"routine",
"issue",
"agent",
] as const;
export type ToolMcpGatewayContextScopeType = (typeof TOOL_MCP_GATEWAY_CONTEXT_SCOPE_TYPES)[number];
export const TOOL_MCP_GATEWAY_TOKEN_SUBJECT_TYPES = ["gateway_client", "heartbeat_run", "board_user", "agent"] as const;
export type ToolMcpGatewayTokenSubjectType = (typeof TOOL_MCP_GATEWAY_TOKEN_SUBJECT_TYPES)[number];
export const TOOL_MCP_GATEWAY_TOKEN_ACTIONS = [
"tools/list",
"tools/call",
"resources/list",
"resources/read",
"prompts/list",
"prompts/get",
] as const;
export type ToolMcpGatewayTokenAction = (typeof TOOL_MCP_GATEWAY_TOKEN_ACTIONS)[number];
export const CONNECTION_TOKEN_ISSUANCE_PATHS = ["exchange", "oauth_access", "static"] as const;
export type ConnectionTokenIssuancePath = (typeof CONNECTION_TOKEN_ISSUANCE_PATHS)[number];
export const CONNECTION_TOKEN_ISSUANCE_OUTCOMES = [
"success",
"denied",
"rate_limited",
"use_env_lease",
"upstream_error",
"failure",
] as const;
export type ConnectionTokenIssuanceOutcome = (typeof CONNECTION_TOKEN_ISSUANCE_OUTCOMES)[number];
export const TOOL_POLICY_TYPES = [
"allow",
"block",
"require_approval",
"trust_rule",
"rate_limit",
] as const;
export type ToolPolicyType = (typeof TOOL_POLICY_TYPES)[number];
export const TOOL_POLICY_DECISIONS = ["allow", "deny", "require_approval", "rate_limited", "defer_runtime"] as const;
export type ToolPolicyDecision = (typeof TOOL_POLICY_DECISIONS)[number];
export const TOOL_INVOCATION_STATUSES = [
"pending",
"authorized",
"denied",
"awaiting_approval",
"executing",
"succeeded",
"failed",
"cancelled",
"timed_out",
"rate_limited",
] as const;
export type ToolInvocationStatus = (typeof TOOL_INVOCATION_STATUSES)[number];
export const TOOL_INVOCATION_APPROVAL_STATES = [
"not_required",
"required",
"pending",
"approved",
"rejected",
"expired",
] as const;
export type ToolInvocationApprovalState = (typeof TOOL_INVOCATION_APPROVAL_STATES)[number];
export const TOOL_ACTION_REQUEST_STATUSES = [
"pending",
"approved",
"executing",
"rejected",
"expired",
"cancelled",
"executed",
"failed",
] as const;
export type ToolActionRequestStatus = (typeof TOOL_ACTION_REQUEST_STATUSES)[number];
export const TOOL_AUDIT_EVENT_TYPES = [
"discovery",
"policy_decision",
"invocation_created",
"call_started",
"call_completed",
"call_failed",
"call_denied",
"approval_requested",
"approval_resolved",
"session_revoked",
"trust_rule_created",
"trust_rule_revoked",
"trust_rule_used",
"runtime_started",
"runtime_stopped",
"rate_limited",
] as const;
export type ToolAuditEventType = (typeof TOOL_AUDIT_EVENT_TYPES)[number];
export const TOOL_AUDIT_OUTCOMES = ["pending", "success", "failure", "denied", "timeout", "cancelled"] as const;
export type ToolAuditOutcome = (typeof TOOL_AUDIT_OUTCOMES)[number];
/**
* Connection-level lifecycle events surfaced on the per-app Activity tab
* alongside tool-call events (PAP-11284). These are derived from the
* company activity log rows scoped to a single tool connection.
*/
export const TOOL_CONNECTION_LIFECYCLE_EVENT_TYPES = [
"app_connected",
"app_paused",
"app_resumed",
"allowlist_changed",
"reconnected",
"disconnected",
"actions_quarantined",
] as const;
export type ToolConnectionLifecycleEventType = (typeof TOOL_CONNECTION_LIFECYCLE_EVENT_TYPES)[number];
export const TOOL_RUNTIME_KINDS = ["remote_session", "local_stdio"] as const;
export type ToolRuntimeKind = (typeof TOOL_RUNTIME_KINDS)[number];
export const TOOL_RUNTIME_SLOT_STATUSES = ["starting", "running", "idle", "stopped", "failed", "disabled", "error"] as const;
export type ToolRuntimeSlotStatus = (typeof TOOL_RUNTIME_SLOT_STATUSES)[number];
export const TOOL_RATE_LIMIT_WINDOW_KINDS = ["minute", "hour", "day", "month"] as const;
export type ToolRateLimitWindowKind = (typeof TOOL_RATE_LIMIT_WINDOW_KINDS)[number];
export const TOOL_ACCESS_ACTIVITY_ACTIONS = [
"tool_application.created",
"tool_application.updated",
"tool_application.archived",
"tool_connection.created",
"tool_connection.updated",
"tool_connection.tested",
"tool_connection.catalog_refreshed",
"tool_profile.created",
"tool_profile.updated",
"tool_profile.duplicated",
"tool_profile.deleted",
"tool_profile.new_tools_reviewed",
"tool_profile.bound",
"tool_profile.unbound",
"tool_policy.created",
"tool_policy.updated",
"tool_policy.disabled",
"tool_trust_rule.created",
"tool_trust_rule.revoked",
"tool_runtime_slot.started",
"tool_runtime_slot.stopped",
"tool_action_request.created",
"tool_action_request.resolved",
] as const;
export type ToolAccessActivityAction = (typeof TOOL_ACCESS_ACTIVITY_ACTIONS)[number];
// ---------------------------------------------------------------------------
// Plugin System — see doc/plugins/PLUGIN_SPEC.md for the full specification
// ---------------------------------------------------------------------------
/**
* The current version of the Plugin API contract.
*
* Increment this value whenever a breaking change is made to the plugin API
* so that the host can reject incompatible plugin manifests.
*
* @see PLUGIN_SPEC.md §4 — Versioning
*/
export const PLUGIN_API_VERSION = 1 as const;
/**
* Lifecycle statuses for an installed plugin.
*
* State machine: installed → ready | error, ready → disabled | error | upgrade_pending | uninstalled,
* disabled → ready | uninstalled, error → ready | uninstalled,
* upgrade_pending → ready | error | uninstalled, uninstalled → installed (reinstall).
*
* @see {@link PluginStatus} — inferred union type
* @see PLUGIN_SPEC.md §21.3 `plugins.status`
*/
export const PLUGIN_STATUSES = [
"installed",
"ready",
"disabled",
"error",
"upgrade_pending",
"uninstalled",
] as const;
export type PluginStatus = (typeof PLUGIN_STATUSES)[number];
/**
* Plugin classification categories. A plugin declares one or more categories
* in its manifest to describe its primary purpose.
*
* @see PLUGIN_SPEC.md §6.2
*/
export const PLUGIN_CATEGORIES = [
"connector",
"workspace",
"automation",
"ui",
] as const;
export type PluginCategory = (typeof PLUGIN_CATEGORIES)[number];
/**
* Named permissions the host grants to a plugin. Plugins declare required
* capabilities in their manifest; the host enforces them at runtime via the
* plugin capability validator.
*
* Grouped into: Data Read, Data Write, Plugin State, Runtime/Integration,
* Agent Tools, and UI.
*
* @see PLUGIN_SPEC.md §15 — Capability Model
*/
export const PLUGIN_CAPABILITIES = [
"ai.connections.route",
// Data Read
"companies.read",
"projects.read",
"projects.instance-secrets",
"projects.git-credentials",
"project.workspaces.read",
"execution.workspaces.read",
"workspaces.manage",
"issues.read",
"issue.relations.read",
"issue.subtree.read",
"issue.comments.read",
// Read pending issue-thread interactions (decision cards) on an issue.
"issue.interactions.read",
// Read issue attachment metadata and, via the capability-scoped host
// bridge, attachment content bytes (bytes-only, company-scoped, audit-logged).
"issue.attachments.read",
// Read company approvals (list + get). The host redacts approval payloads to
// match the web app's own approval read surface.
"approvals.read",
"issue.documents.read",
"agents.read",
"agents.lifecycle.manage",
"goals.read",
"goals.create",
"goals.update",
"activity.read",
"costs.read",
"issues.orchestration.read",
"access.members.read",
"access.invites.read",
"authorization.grants.read",
"authorization.policies.read",
"authorization.audit.read",
"database.namespace.read",
// Data Write
"issues.create",
"issues.update",
"issue.relations.write",
"issues.checkout",
"issues.wakeup",
"issue.comments.create",
"issue.comments.create_human_attributed",
"issue.interactions.create",
// Respond to (accept/reject) an issue-thread interaction on behalf of a
// paired board user. Impersonation surface: the host independently
// re-verifies the actor is an active human member of the company at apply
// time (never trusts plugin-supplied identity), matching the web app's
// board-only interaction resolve route.
"issue.interactions.respond",
// Decide (approve/reject) a company approval on behalf of a paired board
// user. Same apply-time active-human-member re-verification as above; the
// web app's approval decision routes are board-only.
"approvals.respond",
"issue.documents.write",
"projects.managed",
"routines.managed",
"skills.managed",
"agents.pause",
"agents.resume",
"agents.invoke",
"agents.managed",
"access.members.write",
"access.invites.write",
"authorization.grants.write",
"authorization.policies.write",
"agent.sessions.create",
"agent.sessions.list",
"agent.sessions.send",
"agent.sessions.close",
"activity.log.write",
"metrics.write",
"telemetry.track",
"database.namespace.migrate",
"database.namespace.write",
"external.objects.detect",
"external.objects.read",
"external.objects.write",
"external.objects.refresh",
// Plugin State
"plugin.state.read",
"plugin.state.write",
// Runtime / Integration
"events.subscribe",
"events.emit",
"jobs.schedule",
"webhooks.receive",
"api.routes.register",
"http.outbound",
"secrets.read-ref",
"environment.drivers.register",
"local.folders",
// Agent Tools
"agent.tools.register",
// Connectors
"connectors.provide",
// UI
"instance.settings.register",
"ui.sidebar.register",
"ui.page.register",
"ui.detailTab.register",
"ui.dashboardWidget.register",
"ui.commentAnnotation.register",
"ui.action.register",
] as const;
export type PluginCapability = (typeof PLUGIN_CAPABILITIES)[number];
export const PLUGIN_DATABASE_NAMESPACE_MODES = ["schema"] as const;
export type PluginDatabaseNamespaceMode = (typeof PLUGIN_DATABASE_NAMESPACE_MODES)[number];
export const PLUGIN_DATABASE_NAMESPACE_STATUSES = [
"active",
"migration_failed",
] as const;
export type PluginDatabaseNamespaceStatus = (typeof PLUGIN_DATABASE_NAMESPACE_STATUSES)[number];
export const PLUGIN_DATABASE_MIGRATION_STATUSES = [
"applied",
"failed",
] as const;
export type PluginDatabaseMigrationStatus = (typeof PLUGIN_DATABASE_MIGRATION_STATUSES)[number];
export const PLUGIN_DATABASE_CORE_READ_TABLES = [
"companies",
"projects",
"goals",
"agents",
"issues",
"issue_documents",
"issue_relations",
"issue_comments",
"heartbeat_runs",
"cost_events",
"approvals",
"issue_approvals",
"budget_incidents",
] as const;
export type PluginDatabaseCoreReadTable = (typeof PLUGIN_DATABASE_CORE_READ_TABLES)[number];
export const PLUGIN_API_ROUTE_METHODS = ["GET", "POST", "PATCH", "DELETE"] as const;
export type PluginApiRouteMethod = (typeof PLUGIN_API_ROUTE_METHODS)[number];
export const PLUGIN_API_ROUTE_AUTH_MODES = ["board", "agent", "board-or-agent", "webhook"] as const;
export type PluginApiRouteAuthMode = (typeof PLUGIN_API_ROUTE_AUTH_MODES)[number];
export const PLUGIN_API_ROUTE_CHECKOUT_POLICIES = [
"none",
"required-for-agent-in-progress",
"always-for-agent",
] as const;
export type PluginApiRouteCheckoutPolicy = (typeof PLUGIN_API_ROUTE_CHECKOUT_POLICIES)[number];
/**
* UI extension slot types. Each slot type corresponds to a mount point in the
* Paperclip UI where plugin components can be rendered.
*
* @see PLUGIN_SPEC.md §19 — UI Extension Model
*/
export const PLUGIN_UI_SLOT_TYPES = [
"page",
"detailTab",
"taskDetailView",
"dashboardWidget",
"sidebar",
"routeSidebar",
"sidebarPanel",
"projectSidebarItem",
"globalToolbarButton",
"appShellOverlay",
"organizationSwitcher",
"toolbarButton",
"contextMenuItem",
"commentAnnotation",
"commentContextMenuItem",
"settingsPage",
"companySettingsPage",
] as const;
export type PluginUiSlotType = (typeof PLUGIN_UI_SLOT_TYPES)[number];
export const WORKSPACE_OVERVIEW_DEFAULT_LIMIT = 50;
export const HEARTBEAT_RUN_LIST_DEFAULT_LIMIT = 200;
export const HEARTBEAT_RUN_LIST_MAX_LIMIT = 1000;
export const WORKSPACE_OVERVIEW_MAX_LIMIT = 100;
export const WORKSPACE_OVERVIEW_LINKED_ISSUE_LIMIT = 4;
/**
* Reserved company-scoped route segments that plugin page routes may not claim.
*
* These map to first-class host pages under `/:companyPrefix/...`.
*/
export const PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS = [
"dashboard",
"onboarding",
"companies",
"company",
"settings",
"plugins",
"org",
"agents",
"projects",
"issues",
"goals",
"approvals",
"costs",
"activity",
"inbox",
"workspaces",
"design-guide",
"tests",
] as const;
export type PluginReservedCompanyRouteSegment =
(typeof PLUGIN_RESERVED_COMPANY_ROUTE_SEGMENTS)[number];
/**
* Reserved route segments under `/:companyPrefix/company/settings/...` that
* plugin company settings pages may not claim.
*/
export const PLUGIN_RESERVED_COMPANY_SETTINGS_ROUTE_SEGMENTS = [
"general",
"environments",
"access",
"members",
"invites",
"secrets",
"instance",
] as const;
export type PluginReservedCompanySettingsRouteSegment =
(typeof PLUGIN_RESERVED_COMPANY_SETTINGS_ROUTE_SEGMENTS)[number];
/**
* Launcher placement zones describe where a plugin-owned launcher can appear
* in the host UI. These are intentionally aligned with current slot surfaces
* so manifest authors can describe launch intent without coupling to a single
* component implementation detail.
*/
export const PLUGIN_LAUNCHER_PLACEMENT_ZONES = [
"page",
"detailTab",
"taskDetailView",
"dashboardWidget",
"sidebar",
"sidebarPanel",
"projectSidebarItem",
"globalToolbarButton",
"toolbarButton",
"contextMenuItem",
"commentAnnotation",
"commentContextMenuItem",
"settingsPage",
] as const;
export type PluginLauncherPlacementZone = (typeof PLUGIN_LAUNCHER_PLACEMENT_ZONES)[number];
/**
* Launcher action kinds describe what the launcher does when activated.
*/
export const PLUGIN_LAUNCHER_ACTIONS = [
"navigate",
"openModal",
"openDrawer",
"openPopover",
"performAction",
"deepLink",
] as const;
export type PluginLauncherAction = (typeof PLUGIN_LAUNCHER_ACTIONS)[number];
/**
* Optional size hints the host can use when rendering plugin-owned launcher
* destinations such as overlays, drawers, or full page handoffs.
*/
export const PLUGIN_LAUNCHER_BOUNDS = [
"inline",
"compact",
"default",
"wide",
"full",
] as const;
export type PluginLauncherBounds = (typeof PLUGIN_LAUNCHER_BOUNDS)[number];
/**
* Render environments describe the container a launcher expects after it is
* activated. The current host may map these to concrete UI primitives.
*/
export const PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS = [
"hostInline",
"hostOverlay",
"hostRoute",
"external",
"iframe",
] as const;
export type PluginLauncherRenderEnvironment =
(typeof PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS)[number];
/**
* Entity types that a `detailTab` UI slot can attach to.
*
* @see PLUGIN_SPEC.md §19.3 — Detail Tabs
*/
export const PLUGIN_UI_SLOT_ENTITY_TYPES = [
"project",
"issue",
"agent",
"goal",
"run",
"comment",
"execution_workspace",
"project_workspace",
] as const;
export type PluginUiSlotEntityType = (typeof PLUGIN_UI_SLOT_ENTITY_TYPES)[number];
/**
* Scope kinds for plugin state storage. Determines the granularity at which
* a plugin stores key-value state data.
*
* @see PLUGIN_SPEC.md §21.3 `plugin_state.scope_kind`
*/
export const PLUGIN_STATE_SCOPE_KINDS = [
"instance",
"company",
"project",
"project_workspace",
"agent",
"issue",
"goal",
"run",
] as const;
export type PluginStateScopeKind = (typeof PLUGIN_STATE_SCOPE_KINDS)[number];
/** Statuses for a plugin's scheduled job definition. */
export const PLUGIN_JOB_STATUSES = [
"active",
"paused",
"failed",
] as const;
export type PluginJobStatus = (typeof PLUGIN_JOB_STATUSES)[number];
/** Statuses for individual job run executions. */
export const PLUGIN_JOB_RUN_STATUSES = [
"pending",
"queued",
"running",
"succeeded",
"failed",
"cancelled",
] as const;
export type PluginJobRunStatus = (typeof PLUGIN_JOB_RUN_STATUSES)[number];
/** What triggered a particular job run. */
export const PLUGIN_JOB_RUN_TRIGGERS = [
"schedule",
"manual",
"retry",
] as const;
export type PluginJobRunTrigger = (typeof PLUGIN_JOB_RUN_TRIGGERS)[number];
/** Statuses for inbound webhook deliveries. */
export const PLUGIN_WEBHOOK_DELIVERY_STATUSES = [
"pending",
"success",
"failed",
] as const;
export type PluginWebhookDeliveryStatus = (typeof PLUGIN_WEBHOOK_DELIVERY_STATUSES)[number];
/**
* Core domain event types that plugins can subscribe to via the
* `events.subscribe` capability.
*
* @see PLUGIN_SPEC.md §16 — Event System
*/
export const PLUGIN_EVENT_TYPES = [
"company.created",
"company.updated",
"project.created",
"project.updated",
"project.workspace_created",
"project.workspace_updated",
"project.workspace_deleted",
"issue.created",
"issue.updated",
"issue.comment.created",
"issue.document.created",
"issue.document.updated",
"issue.document.deleted",
"issue.relations.updated",
"issue.checked_out",
"issue.released",
"issue.assignment_wakeup_requested",
"agent.created",
"agent.updated",
"agent.status_changed",
"agent.error_cleared",
"agent.run.started",
"agent.run.finished",
"agent.run.failed",
"agent.run.cancelled",
"goal.created",
"goal.updated",
"approval.created",
"approval.decided",
"budget.incident.opened",
"budget.incident.resolved",
"cost_event.created",
"activity.logged",
] as const;
export type PluginEventType = (typeof PLUGIN_EVENT_TYPES)[number];
/**
* Error codes returned by the plugin bridge when a UI → worker call fails.
*
* @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
*/
export const PLUGIN_BRIDGE_ERROR_CODES = [
"WORKER_UNAVAILABLE",
"CAPABILITY_DENIED",
"INVOCATION_SCOPE_DENIED",
"WORKER_ERROR",
"TIMEOUT",
"UNKNOWN",
] as const;
export type PluginBridgeErrorCode = (typeof PLUGIN_BRIDGE_ERROR_CODES)[number];