Add issue subtree hold preview foundation

packages/shared/src/api.ts

@@ -6,6 +6,8 @@ export const API = {
   agents: `${API_PREFIX}/agents`,
   projects: `${API_PREFIX}/projects`,
   issues: `${API_PREFIX}/issues`,
+  issueTreeControl: `${API_PREFIX}/issues/:issueId/tree-control`,
+  issueTreeHolds: `${API_PREFIX}/issues/:issueId/tree-holds`,
   goals: `${API_PREFIX}/goals`,
   approvals: `${API_PREFIX}/approvals`,
   secrets: `${API_PREFIX}/secrets`,

packages/shared/src/constants.ts

@@ -170,6 +170,15 @@ export type IssueOriginKind = BuiltInIssueOriginKind | PluginIssueOriginKind;
 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] as const;
 export type SystemIssueDocumentKey = (typeof SYSTEM_ISSUE_DOCUMENT_KEYS)[number];

packages/shared/src/index.ts

@@ -21,6 +21,9 @@ export {
   ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES,
   ISSUE_ORIGIN_KINDS,
   ISSUE_RELATION_TYPES,
+  ISSUE_TREE_CONTROL_MODES,
+  ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES,
+  ISSUE_TREE_HOLD_STATUSES,
   ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,
   SYSTEM_ISSUE_DOCUMENT_KEYS,
   isSystemIssueDocumentKey,
@@ -120,6 +123,9 @@ export {
   type PluginIssueOriginKind,
   type IssueOriginKind,
   type IssueRelationType,
+  type IssueTreeControlMode,
+  type IssueTreeHoldReleasePolicyStrategy,
+  type IssueTreeHoldStatus,
   type SystemIssueDocumentKey,
   type IssueReferenceSourceKind,
   type IssueExecutionPolicyMode,
@@ -348,6 +354,15 @@ export type {
   LegacyPlanDocument,
   IssueAttachment,
   IssueLabel,
+  IssueTreeControlPreview,
+  IssueTreeHold,
+  IssueTreeHoldMember,
+  IssueTreeHoldReleasePolicy,
+  IssueTreePreviewAgent,
+  IssueTreePreviewIssue,
+  IssueTreePreviewRun,
+  IssueTreePreviewTotals,
+  IssueTreePreviewWarning,
   Goal,
   Approval,
   ApprovalComment,
@@ -644,6 +659,11 @@ export {
   issueDocumentKeySchema,
   upsertIssueDocumentSchema,
   restoreIssueDocumentRevisionSchema,
+  createIssueTreeHoldSchema,
+  issueTreeControlModeSchema,
+  issueTreeHoldReleasePolicySchema,
+  previewIssueTreeControlSchema,
+  releaseIssueTreeHoldSchema,
   type CreateIssue,
   type CreateChildIssue,
   type CreateIssueLabel,
@@ -662,6 +682,9 @@ export {
   type IssueDocumentFormat,
   type UpsertIssueDocument,
   type RestoreIssueDocumentRevision,
+  type CreateIssueTreeHold,
+  type PreviewIssueTreeControl,
+  type ReleaseIssueTreeHold,
   createGoalSchema,
   updateGoalSchema,
   type CreateGoal,

packages/shared/src/types/index.ts

@@ -148,6 +148,17 @@ export type {
   IssueAttachment,
   IssueLabel,
 } from "./issue.js";
+export type {
+  IssueTreeControlPreview,
+  IssueTreeHold,
+  IssueTreeHoldMember,
+  IssueTreeHoldReleasePolicy,
+  IssueTreePreviewAgent,
+  IssueTreePreviewIssue,
+  IssueTreePreviewRun,
+  IssueTreePreviewTotals,
+  IssueTreePreviewWarning,
+} from "./issue-tree-control.js";
 export type { Goal } from "./goal.js";
 export type { Approval, ApprovalComment } from "./approval.js";
 export type {

packages/shared/src/types/issue-tree-control.ts

@@ -0,0 +1,115 @@
+import type {
+  IssueStatus,
+  IssueTreeControlMode,
+  IssueTreeHoldReleasePolicyStrategy,
+  IssueTreeHoldStatus,
+} from "../constants.js";
+
+export interface IssueTreeHoldReleasePolicy {
+  strategy: IssueTreeHoldReleasePolicyStrategy;
+  note?: string | null;
+}
+
+export interface IssueTreePreviewRun {
+  id: string;
+  issueId: string;
+  agentId: string;
+  status: "queued" | "running";
+  startedAt: Date | null;
+  createdAt: Date;
+}
+
+export interface IssueTreePreviewAgent {
+  agentId: string;
+  issueCount: number;
+  activeRunCount: number;
+}
+
+export interface IssueTreePreviewIssue {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  parentId: string | null;
+  depth: number;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+  activeRun: IssueTreePreviewRun | null;
+  activeHoldIds: string[];
+  action: IssueTreeControlMode;
+  skipped: boolean;
+  skipReason: string | null;
+}
+
+export interface IssueTreePreviewWarning {
+  code: string;
+  message: string;
+  issueIds?: string[];
+}
+
+export interface IssueTreePreviewTotals {
+  totalIssues: number;
+  affectedIssues: number;
+  skippedIssues: number;
+  activeRuns: number;
+  queuedRuns: number;
+  affectedAgents: number;
+}
+
+export interface IssueTreeControlPreview {
+  companyId: string;
+  rootIssueId: string;
+  mode: IssueTreeControlMode;
+  generatedAt: Date;
+  releasePolicy: IssueTreeHoldReleasePolicy | null;
+  totals: IssueTreePreviewTotals;
+  countsByStatus: Partial<Record<IssueStatus, number>>;
+  issues: IssueTreePreviewIssue[];
+  skippedIssues: IssueTreePreviewIssue[];
+  activeRuns: IssueTreePreviewRun[];
+  affectedAgents: IssueTreePreviewAgent[];
+  warnings: IssueTreePreviewWarning[];
+}
+
+export interface IssueTreeHoldMember {
+  id: string;
+  companyId: string;
+  holdId: string;
+  issueId: string;
+  parentIssueId: string | null;
+  depth: number;
+  issueIdentifier: string | null;
+  issueTitle: string;
+  issueStatus: IssueStatus;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+  activeRunId: string | null;
+  activeRunStatus: string | null;
+  skipped: boolean;
+  skipReason: string | null;
+  createdAt: Date;
+}
+
+export interface IssueTreeHold {
+  id: string;
+  companyId: string;
+  rootIssueId: string;
+  mode: IssueTreeControlMode;
+  status: IssueTreeHoldStatus;
+  reason: string | null;
+  releasePolicy: IssueTreeHoldReleasePolicy | null;
+  createdByActorType: "user" | "agent" | "system";
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  createdByRunId: string | null;
+  releasedAt: Date | null;
+  releasedByActorType: "user" | "agent" | "system" | null;
+  releasedByAgentId: string | null;
+  releasedByUserId: string | null;
+  releasedByRunId: string | null;
+  releaseReason: string | null;
+  releaseMetadata: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+  members?: IssueTreeHoldMember[];
+}

packages/shared/src/validators/index.ts

@@ -197,6 +197,17 @@ export {
   type RestoreIssueDocumentRevision,
 } from "./issue.js";
 
+export {
+  createIssueTreeHoldSchema,
+  issueTreeControlModeSchema,
+  issueTreeHoldReleasePolicySchema,
+  previewIssueTreeControlSchema,
+  releaseIssueTreeHoldSchema,
+  type CreateIssueTreeHold,
+  type PreviewIssueTreeControl,
+  type ReleaseIssueTreeHold,
+} from "./issue-tree-control.js";
+
 export {
   createIssueWorkProductSchema,
   updateIssueWorkProductSchema,

packages/shared/src/validators/issue-tree-control.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import {
+  ISSUE_TREE_CONTROL_MODES,
+  ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES,
+} from "../constants.js";
+
+export const issueTreeControlModeSchema = z.enum(ISSUE_TREE_CONTROL_MODES);
+
+export const issueTreeHoldReleasePolicySchema = z
+  .object({
+    strategy: z.enum(ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES).default("manual"),
+    note: z.string().trim().min(1).max(500).optional().nullable(),
+  })
+  .strict();
+
+export const previewIssueTreeControlSchema = z
+  .object({
+    mode: issueTreeControlModeSchema,
+    releasePolicy: issueTreeHoldReleasePolicySchema.optional().nullable(),
+  })
+  .strict();
+
+export type PreviewIssueTreeControl = z.infer<typeof previewIssueTreeControlSchema>;
+
+export const createIssueTreeHoldSchema = z
+  .object({
+    mode: issueTreeControlModeSchema,
+    reason: z.string().trim().min(1).max(1000).optional().nullable(),
+    releasePolicy: issueTreeHoldReleasePolicySchema.optional().nullable(),
+  })
+  .strict();
+
+export type CreateIssueTreeHold = z.infer<typeof createIssueTreeHoldSchema>;
+
+export const releaseIssueTreeHoldSchema = z
+  .object({
+    reason: z.string().trim().min(1).max(1000).optional().nullable(),
+    releasePolicy: issueTreeHoldReleasePolicySchema.optional().nullable(),
+    metadata: z.record(z.unknown()).optional().nullable(),
+  })
+  .strict();
+
+export type ReleaseIssueTreeHold = z.infer<typeof releaseIssueTreeHoldSchema>;