@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/src/types.ts

@@ -30,7 +30,7 @@ export const InboxMessageSchema = z.object({
   id: z.uuid(),
   agentId: z.uuid(), // Lead agent who received this
   content: z.string().min(1), // The message content
-  source: z.enum(["slack"]).default("slack"),
+  source: z.enum(["slack", "agentmail"]).default("slack"),
   status: InboxMessageStatusSchema.default("unread"),
 
   // Slack context (for replying)
@@ -53,7 +53,18 @@ export const InboxMessageSchema = z.object({
 export type InboxMessageStatus = z.infer<typeof InboxMessageStatusSchema>;
 export type InboxMessage = z.infer<typeof InboxMessageSchema>;
 
-export const AgentTaskSourceSchema = z.enum(["mcp", "slack", "api", "github"]);
+export const AgentTaskSourceSchema = z.enum([
+  "mcp",
+  "slack",
+  "api",
+  "github",
+  "gitlab",
+  "agentmail",
+  "system",
+  "schedule",
+  "workflow",
+  "linear",
+]);
 export type AgentTaskSource = z.infer<typeof AgentTaskSourceSchema>;
 
 export const AgentTaskSchema = z.object({
@@ -92,13 +103,19 @@ export const AgentTaskSchema = z.object({
   slackThreadTs: z.string().optional(),
   slackUserId: z.string().optional(),
 
-  // GitHub-specific metadata (optional)
-  githubRepo: z.string().optional(),
-  githubEventType: z.string().optional(),
-  githubNumber: z.number().int().optional(),
-  githubCommentId: z.number().int().optional(),
-  githubAuthor: z.string().optional(),
-  githubUrl: z.string().optional(),
+  // VCS metadata (GitHub / GitLab — provider-agnostic)
+  vcsProvider: z.enum(["github", "gitlab"]).optional(),
+  vcsRepo: z.string().optional(),
+  vcsEventType: z.string().optional(),
+  vcsNumber: z.number().int().optional(),
+  vcsCommentId: z.number().int().optional(),
+  vcsAuthor: z.string().optional(),
+  vcsUrl: z.string().optional(),
+
+  // AgentMail-specific metadata (optional)
+  agentmailInboxId: z.string().optional(),
+  agentmailMessageId: z.string().optional(),
+  agentmailThreadId: z.string().optional(),
 
   // Mention-to-task metadata (optional)
   mentionMessageId: z.uuid().optional(),
@@ -106,6 +123,26 @@ export const AgentTaskSchema = z.object({
 
   // Epic association (optional)
   epicId: z.uuid().optional(),
+
+  // Working directory (optional — must be an absolute path for the agent process)
+  dir: z.string().min(1).startsWith("/").optional(),
+
+  // Session attachment (optional)
+  parentTaskId: z.uuid().optional(),
+  claudeSessionId: z.string().optional(),
+
+  // Model selection (optional — defaults to "opus" via runner)
+  model: z.enum(["haiku", "sonnet", "opus"]).optional(),
+
+  // Schedule linking (optional — set when task was created by a schedule)
+  scheduleId: z.uuid().optional(),
+
+  // Workflow linking (optional — set when task was created by a workflow)
+  workflowRunId: z.string().uuid().nullable().optional(),
+  workflowRunStepId: z.string().uuid().nullable().optional(),
+
+  // Structured output schema (optional — JSON Schema that task output must conform to)
+  outputSchema: z.record(z.string(), z.unknown()).optional(),
 });
 
 export const AgentStatusSchema = z.enum(["idle", "busy", "offline"]);
@@ -124,12 +161,24 @@ export const AgentSchema = z.object({
   // Personal CLAUDE.md content (max 64KB)
   claudeMd: z.string().max(65536).optional(),
 
+  // Soul: Persona, behavioral directives (injected via --append-system-prompt)
+  soulMd: z.string().max(65536).optional(),
+  // Identity: Expertise, working style, self-evolution notes (injected via --append-system-prompt)
+  identityMd: z.string().max(65536).optional(),
+  // Setup script: Runs at container start, agent-evolved (synced to /workspace/start-up.sh)
+  setupScript: z.string().max(65536).optional(),
+  // Tools/environment reference: Operational knowledge (synced to /workspace/TOOLS.md)
+  toolsMd: z.string().max(65536).optional(),
+
   // Concurrency limit (defaults to 1 for backwards compatibility)
   maxTasks: z.number().int().min(1).max(20).optional(),
 
   // Polling limit tracking (consecutive empty polls)
   emptyPollCount: z.number().int().min(0).optional(),
 
+  // Last session activity timestamp (updated on tool calls, task updates, etc.)
+  lastActivityAt: z.iso.datetime().optional(),
+
   createdAt: z.iso.datetime().default(() => new Date().toISOString()),
   lastUpdatedAt: z.iso.datetime().default(() => new Date().toISOString()),
 });
@@ -145,6 +194,50 @@ export type AgentStatus = z.infer<typeof AgentStatusSchema>;
 export type Agent = z.infer<typeof AgentSchema>;
 export type AgentWithTasks = z.infer<typeof AgentWithTasksSchema>;
 
+// ============================================================================
+// Context Versioning Types
+// ============================================================================
+
+export const ChangeSourceSchema = z.enum([
+  "self_edit",
+  "lead_coaching",
+  "api",
+  "system",
+  "session_sync",
+]);
+
+export const VersionableFieldSchema = z.enum([
+  "soulMd",
+  "identityMd",
+  "toolsMd",
+  "claudeMd",
+  "setupScript",
+]);
+
+export const ContextVersionSchema = z.object({
+  id: z.uuid(),
+  agentId: z.uuid(),
+  field: VersionableFieldSchema,
+  content: z.string(),
+  version: z.number().int().min(1),
+  changeSource: ChangeSourceSchema,
+  changedByAgentId: z.uuid().nullable(),
+  changeReason: z.string().nullable(),
+  contentHash: z.string(),
+  previousVersionId: z.uuid().nullable(),
+  createdAt: z.iso.datetime(),
+});
+
+export type ChangeSource = z.infer<typeof ChangeSourceSchema>;
+export type VersionableField = z.infer<typeof VersionableFieldSchema>;
+export type ContextVersion = z.infer<typeof ContextVersionSchema>;
+
+export type VersionMeta = {
+  changeSource?: ChangeSource;
+  changedByAgentId?: string | null;
+  changeReason?: string | null;
+};
+
 // Channel Types
 export const ChannelTypeSchema = z.enum(["public", "dm"]);
 
@@ -291,12 +384,23 @@ export const ScheduledTaskSchema = z
     nextRunAt: z.iso.datetime().optional(),
     createdByAgentId: z.uuid().optional(),
     timezone: z.string().default("UTC"),
+    consecutiveErrors: z.number().int().min(0).default(0),
+    lastErrorAt: z.iso.datetime().optional(),
+    lastErrorMessage: z.string().optional(),
+    model: z.enum(["haiku", "sonnet", "opus"]).optional(),
+    scheduleType: z.enum(["recurring", "one_time"]).default("recurring"),
     createdAt: z.iso.datetime(),
     lastUpdatedAt: z.iso.datetime(),
   })
-  .refine((data) => data.cronExpression || data.intervalMs, {
-    message: "Either cronExpression or intervalMs must be provided",
-  });
+  .refine(
+    (data) => {
+      if (data.scheduleType === "one_time") return true;
+      return data.cronExpression || data.intervalMs;
+    },
+    {
+      message: "Either cronExpression or intervalMs must be provided for recurring schedules",
+    },
+  );
 
 export type ScheduledTask = z.infer<typeof ScheduledTaskSchema>;
 
@@ -329,8 +433,10 @@ export const EpicSchema = z.object({
   planDocPath: z.string().optional(),
   slackChannelId: z.string().optional(),
   slackThreadTs: z.string().optional(),
-  githubRepo: z.string().optional(),
-  githubMilestone: z.string().optional(),
+  vcsProvider: z.enum(["github", "gitlab"]).optional(),
+  vcsRepo: z.string().optional(),
+  vcsMilestone: z.string().optional(),
+  nextSteps: z.string().optional(), // Lead's notes on what to do next for this epic
   createdAt: z.iso.datetime(),
   lastUpdatedAt: z.iso.datetime(),
   startedAt: z.iso.datetime().optional(),
@@ -353,3 +459,360 @@ export const EpicWithProgressSchema = EpicSchema.extend({
 });
 
 export type EpicWithProgress = z.infer<typeof EpicWithProgressSchema>;
+
+// ============================================================================
+// Swarm Config Types (Centralized Environment/Config Management)
+// ============================================================================
+
+export const SwarmConfigScopeSchema = z.enum(["global", "agent", "repo"]);
+
+export const SwarmConfigSchema = z.object({
+  id: z.string().uuid(),
+  scope: SwarmConfigScopeSchema,
+  scopeId: z.string().nullable(), // agentId or repoId, null for global
+  key: z.string().min(1).max(255),
+  value: z.string(),
+  isSecret: z.boolean(),
+  envPath: z.string().nullable(),
+  description: z.string().nullable(),
+  createdAt: z.string(),
+  lastUpdatedAt: z.string(),
+});
+
+export type SwarmConfigScope = z.infer<typeof SwarmConfigScopeSchema>;
+export type SwarmConfig = z.infer<typeof SwarmConfigSchema>;
+
+// ============================================================================
+// Swarm Repos Types (Centralized Repository Management)
+// ============================================================================
+
+export const SwarmRepoSchema = z.object({
+  id: z.string().uuid(),
+  url: z.string().min(1),
+  name: z.string().min(1).max(100),
+  clonePath: z.string().min(1),
+  defaultBranch: z.string().default("main"),
+  autoClone: z.boolean().default(true),
+  createdAt: z.string(),
+  lastUpdatedAt: z.string(),
+});
+
+export type SwarmRepo = z.infer<typeof SwarmRepoSchema>;
+
+// ============================================================================
+// Agent Memory Types (Persistent Memory System)
+// ============================================================================
+
+export const AgentMemoryScopeSchema = z.enum(["agent", "swarm"]);
+export const AgentMemorySourceSchema = z.enum([
+  "manual",
+  "file_index",
+  "session_summary",
+  "task_completion",
+]);
+
+export const AgentMemorySchema = z.object({
+  id: z.string().uuid(),
+  agentId: z.string().uuid().nullable(),
+  scope: AgentMemoryScopeSchema,
+  name: z.string().min(1).max(500),
+  content: z.string(),
+  summary: z.string().nullable(),
+  source: AgentMemorySourceSchema,
+  sourceTaskId: z.string().uuid().nullable(),
+  sourcePath: z.string().nullable(),
+  chunkIndex: z.number().int().min(0).default(0),
+  totalChunks: z.number().int().min(1).default(1),
+  tags: z.array(z.string()),
+  createdAt: z.string(),
+  accessedAt: z.string(),
+});
+
+export type AgentMemoryScope = z.infer<typeof AgentMemoryScopeSchema>;
+export type AgentMemorySource = z.infer<typeof AgentMemorySourceSchema>;
+export type AgentMemory = z.infer<typeof AgentMemorySchema>;
+
+// ============================================================================
+// Active Session Types (runner session tracking)
+// ============================================================================
+
+export const ActiveSessionSchema = z.object({
+  id: z.uuid(),
+  agentId: z.uuid(),
+  taskId: z.string().nullable(),
+  triggerType: z.string(),
+  inboxMessageId: z.string().nullable(),
+  taskDescription: z.string().nullable(),
+  startedAt: z.iso.datetime(),
+  lastHeartbeatAt: z.iso.datetime(),
+});
+
+export type ActiveSession = z.infer<typeof ActiveSessionSchema>;
+
+// ============================================================================
+// Workflow Engine Types
+// ============================================================================
+
+// --- Retry Policy ---
+
+export const RetryPolicySchema = z.object({
+  maxRetries: z.number().int().min(0).default(3),
+  strategy: z.enum(["exponential", "static", "linear"]).default("exponential"),
+  baseDelayMs: z.number().int().min(0).default(1000),
+  maxDelayMs: z.number().int().min(0).default(60000),
+});
+export type RetryPolicy = z.infer<typeof RetryPolicySchema>;
+
+// --- Executor Metadata ---
+
+export const ExecutorMetaSchema = z.object({
+  runId: z.string().uuid(),
+  stepId: z.string().uuid(),
+  nodeId: z.string(),
+  workflowId: z.string().uuid(),
+  dryRun: z.boolean().default(false),
+});
+export type ExecutorMeta = z.infer<typeof ExecutorMetaSchema>;
+
+// --- Validation ---
+
+export const ValidationResultSchema = z.object({
+  pass: z.boolean(),
+  reasoning: z.string(),
+  confidence: z.number().min(0).max(1),
+});
+export type ValidationResult = z.infer<typeof ValidationResultSchema>;
+
+export const StepValidationConfigSchema = z.object({
+  executor: z.string().default("validate"),
+  config: z.record(z.string(), z.unknown()),
+  mustPass: z.boolean().default(false),
+  retry: RetryPolicySchema.optional(),
+});
+export type StepValidationConfig = z.infer<typeof StepValidationConfigSchema>;
+
+// --- Workflow Node (nodes-with-next) ---
+
+export const WorkflowNodeSchema = z.object({
+  id: z.string().describe("Unique node identifier, used in 'next' and 'inputs' mappings"),
+  type: z
+    .string()
+    .describe("Executor type: 'agent-task', 'script', 'raw-llm', 'validate', 'property-match'"),
+  label: z.string().optional().describe("Human-readable label for UI display"),
+  config: z
+    .record(z.string(), z.unknown())
+    .describe(
+      "Executor-specific config. For agent-task: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. " +
+        "Values support {{interpolation}} from the node's inputs context. " +
+        "NOTE: config.outputSchema on agent-task nodes validates the AGENT's raw JSON output, " +
+        "while node-level outputSchema validates the EXECUTOR's return value ({taskId, taskOutput}).",
+    ),
+  next: z
+    .union([z.string(), z.record(z.string(), z.string())])
+    .optional()
+    .describe(
+      "Next node(s): string for simple chaining, or record for port-based routing ({pass: 'a', fail: 'b'})",
+    ),
+  validation: StepValidationConfigSchema.optional(),
+  retry: RetryPolicySchema.optional(),
+  // REQUIRED for cross-node data access — without this, only 'trigger' and 'input' are available for interpolation.
+  inputs: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe(
+      "REQUIRED for cross-node data access. Maps local names to context paths. " +
+        "Without this, upstream step outputs are NOT available for interpolation — only 'trigger' and 'input' are. " +
+        'Example: { "cityData": "generate-city" } → use {{cityData.taskOutput.field}} in config templates. ' +
+        'For trigger data: { "pr": "trigger.pullRequest" }.',
+    ),
+  inputSchema: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("JSON Schema to validate resolved inputs before execution"),
+  outputSchema: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe(
+      "JSON Schema to validate the executor's output (e.g. {taskId, taskOutput} for agent-task). " +
+        "Different from config.outputSchema which validates the agent's raw output.",
+    ),
+});
+export type WorkflowNode = z.infer<typeof WorkflowNodeSchema>;
+
+// --- Workflow Edge (derived — for UI rendering) ---
+
+export const WorkflowEdgeSchema = z.object({
+  id: z.string(),
+  source: z.string(),
+  sourcePort: z.string(),
+  target: z.string(),
+});
+export type WorkflowEdge = z.infer<typeof WorkflowEdgeSchema>;
+
+// --- Workflow Definition (nodes-only, no explicit edges) ---
+
+export const WorkflowDefinitionSchema = z.object({
+  nodes: z.array(WorkflowNodeSchema).min(1),
+});
+export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
+
+// --- Trigger Configuration ---
+
+export const TriggerConfigSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("webhook"),
+    hmacSecret: z.string().optional(),
+    hmacHeader: z.string().default("X-Hub-Signature-256"),
+  }),
+  z.object({
+    type: z.literal("schedule"),
+    scheduleId: z.string().uuid(),
+  }),
+]);
+export type TriggerConfig = z.infer<typeof TriggerConfigSchema>;
+
+// --- Cooldown Configuration ---
+
+export const CooldownConfigSchema = z
+  .object({
+    hours: z.number().min(0).optional(),
+    minutes: z.number().min(0).optional(),
+    seconds: z.number().min(0).optional(),
+  })
+  .refine((v) => v.hours !== undefined || v.minutes !== undefined || v.seconds !== undefined, {
+    message: "At least one of hours, minutes, or seconds is required",
+  });
+export type CooldownConfig = z.infer<typeof CooldownConfigSchema>;
+
+// --- Input Value Resolution ---
+
+export const InputValueSchema = z.union([
+  z
+    .string()
+    .regex(/^\$\{.+\}$/), // env var: ${MY_VAR}
+  z
+    .string()
+    .regex(/^secret\..+$/), // swarm secret: secret.OPENAI_KEY
+  z.string(), // literal value
+]);
+export type InputValue = z.infer<typeof InputValueSchema>;
+
+// --- Workflow Template ---
+
+export const WorkflowTemplateSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  description: z.string(),
+  category: z.string(),
+  variables: z.array(
+    z.object({
+      name: z.string(),
+      description: z.string(),
+      type: z.enum(["string", "number", "boolean"]),
+      default: z.unknown().optional(),
+      required: z.boolean().default(true),
+    }),
+  ),
+  definition: WorkflowDefinitionSchema,
+});
+export type WorkflowTemplate = z.infer<typeof WorkflowTemplateSchema>;
+
+// --- Workflow Snapshot (for version history) ---
+
+export const WorkflowSnapshotSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  definition: WorkflowDefinitionSchema,
+  triggers: z.array(TriggerConfigSchema),
+  cooldown: CooldownConfigSchema.optional(),
+  input: z.record(z.string(), InputValueSchema).optional(),
+  triggerSchema: z.record(z.string(), z.unknown()).optional(),
+  enabled: z.boolean(),
+});
+export type WorkflowSnapshot = z.infer<typeof WorkflowSnapshotSchema>;
+
+// --- Workflow ---
+
+export const WorkflowSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  description: z.string().optional(),
+  enabled: z.boolean(),
+  definition: WorkflowDefinitionSchema,
+  triggers: z.array(TriggerConfigSchema).default([]),
+  cooldown: CooldownConfigSchema.optional(),
+  input: z.record(z.string(), InputValueSchema).optional(),
+  triggerSchema: z.record(z.string(), z.unknown()).optional(),
+  createdByAgentId: z.string().uuid().optional(),
+  createdAt: z.string(),
+  lastUpdatedAt: z.string(),
+});
+export type Workflow = z.infer<typeof WorkflowSchema>;
+
+// --- Workflow Version ---
+
+export const WorkflowVersionSchema = z.object({
+  id: z.string().uuid(),
+  workflowId: z.string().uuid(),
+  version: z.number().int().min(1),
+  snapshot: WorkflowSnapshotSchema,
+  changedByAgentId: z.string().uuid().optional(),
+  createdAt: z.string(),
+});
+export type WorkflowVersion = z.infer<typeof WorkflowVersionSchema>;
+
+// --- Workflow Run ---
+
+export const WorkflowRunStatusSchema = z.enum([
+  "running",
+  "waiting",
+  "completed",
+  "failed",
+  "skipped",
+]);
+export type WorkflowRunStatus = z.infer<typeof WorkflowRunStatusSchema>;
+
+export const WorkflowRunSchema = z.object({
+  id: z.string().uuid(),
+  workflowId: z.string().uuid(),
+  status: WorkflowRunStatusSchema,
+  triggerData: z.unknown().optional(),
+  context: z.record(z.string(), z.unknown()).optional(),
+  error: z.string().optional(),
+  startedAt: z.string(),
+  lastUpdatedAt: z.string(),
+  finishedAt: z.string().optional(),
+});
+export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
+
+// --- Workflow Run Step ---
+
+export const WorkflowRunStepStatusSchema = z.enum([
+  "pending",
+  "running",
+  "waiting",
+  "completed",
+  "failed",
+  "skipped",
+]);
+export type WorkflowRunStepStatus = z.infer<typeof WorkflowRunStepStatusSchema>;
+
+export const WorkflowRunStepSchema = z.object({
+  id: z.string().uuid(),
+  runId: z.string().uuid(),
+  nodeId: z.string(),
+  nodeType: z.string(),
+  status: WorkflowRunStepStatusSchema,
+  input: z.unknown().optional(),
+  output: z.unknown().optional(),
+  error: z.string().optional(),
+  startedAt: z.string(),
+  finishedAt: z.string().optional(),
+  retryCount: z.number().int().min(0).default(0),
+  maxRetries: z.number().int().min(0).default(3),
+  nextRetryAt: z.string().optional(),
+  idempotencyKey: z.string().optional(),
+  diagnostics: z.string().optional(),
+  nextPort: z.string().optional(),
+});
+export type WorkflowRunStep = z.infer<typeof WorkflowRunStepSchema>;