@artyfacts/claude 1.3.23 → 1.3.25

package/src/context.ts

@@ -1,7 +1,8 @@
 /**
  * Context fetcher for Artyfacts tasks
  * 
- * Fetches full context including organization, project, artifact, and related sections.
+ * Fetches full context including organization, project, goal, and related tasks.
+ * Updated for Schema v2 - tasks are first-class entities linked to goals.
  */
 
 // ============================================================================
@@ -20,6 +21,19 @@ export interface ProjectContext {
   description?: string;
 }
 
+/**
+ * Related task summary (v2)
+ */
+export interface RelatedTaskContext {
+  id: string;
+  title: string;
+  status: 'pending' | 'in_progress' | 'blocked' | 'done';
+  priority?: 'low' | 'medium' | 'high';
+}
+
+/**
+ * Section context (kept for artifact content)
+ */
 export interface SectionContext {
   id: string;
   heading: string;
@@ -28,27 +42,54 @@ export interface SectionContext {
   task_status?: string;
 }
 
-export interface ArtifactContext {
+/**
+ * Goal context (v2 - replaces artifact context for task work)
+ */
+export interface GoalContext {
   id: string;
   title: string;
+  objective?: string;
   summary?: string;
   description?: string;
   artifact_type?: string;
-  sections: SectionContext[];
+  /** Related tasks on this goal */
+  tasks?: RelatedTaskContext[];
+  /** Legacy: sections for content-based artifacts */
+  sections?: SectionContext[];
 }
 
+/** @deprecated Use GoalContext instead */
+export interface ArtifactContext extends GoalContext {}
+
+/**
+ * Full task context (v2)
+ */
 export interface TaskFullContext {
   task: {
+    /** Task UUID */
     id: string;
-    heading: string;
-    content: string;
+    /** Task title */
+    title: string;
+    /** @deprecated Use title instead */
+    heading?: string;
+    /** Task description */
+    description?: string;
+    /** @deprecated Use description instead */
+    content?: string;
+    /** Expected output format and requirements */
     expected_output?: {
       format?: string;
       requirements?: string[];
     };
-    priority?: number;
+    /** Priority level */
+    priority?: 'low' | 'medium' | 'high';
+    /** Dependencies */
+    depends_on?: string[];
   };
-  artifact: ArtifactContext;
+  /** The goal this task belongs to */
+  goal: GoalContext;
+  /** @deprecated Use goal instead */
+  artifact?: GoalContext;
   project?: ProjectContext;
   organization: OrganizationContext;
 }
@@ -98,7 +139,7 @@ export class ContextFetcher {
 // ============================================================================
 
 /**
- * Build a rich prompt with full context
+ * Build a rich prompt with full context (v2)
  */
 export function buildPromptWithContext(context: TaskFullContext): string {
   const parts: string[] = [];
@@ -115,12 +156,13 @@ You have access to Artyfacts MCP tools. USE THEM to complete your task:
 - **create_artifact** - Create new artifacts (documents, specs, reports)
 - **create_section** - Add sections to artifacts (content, tasks, decisions)
 - **update_section** - Update existing sections
-- **create_agent** - Create new AI agents with specific roles
-- **list_artifacts** - Query existing artifacts
-- **list_sections** - Query sections within an artifact
-- **complete_task** - Mark a task as complete
+- **create_task** - Create new tasks under a goal
+- **claim_task** - Claim a task for execution
+- **complete_task** - Mark a task as complete (returns unblocked tasks)
 - **block_task** - Block a task with a reason
-- **create_blocker** - Create a decision blocker
+- **list_tasks** - Query tasks from the queue
+- **list_inbox** - Check pending decisions/approvals
+- **resolve_inbox** - Resolve an inbox item
 
 IMPORTANT: When asked to create agents or update artifacts, USE THE TOOLS. Don't just describe what you would do - actually do it with the tools.
 
@@ -129,7 +171,7 @@ IMPORTANT: When asked to create agents or update artifacts, USE THE TOOLS. Don't
 - Be thorough but concise
 - USE THE TOOLS to take action, don't just analyze
 - If the task requires creating something, use create_artifact or create_section
-- If the task requires creating agents, use create_agent
+- If you complete a task, check the response for unblocked_tasks to see follow-up work
 - If you cannot complete the task, explain why
 
 Format your response as follows:
@@ -159,47 +201,81 @@ Format your response as follows:
     parts.push('');
   }
 
-  // Artifact context
-  parts.push(`## Artifact: ${context.artifact.title}`);
-  if (context.artifact.summary) {
-    parts.push(context.artifact.summary);
-  }
-  if (context.artifact.description) {
+  // Goal context (v2 - was artifact)
+  const goal = context.goal || context.artifact;
+  if (goal) {
+    parts.push(`## Goal: ${goal.title}`);
+    if (goal.objective) {
+      parts.push(`**Objective:** ${goal.objective}`);
+    }
+    if (goal.summary) {
+      parts.push(goal.summary);
+    }
+    if (goal.description) {
+      parts.push('');
+      parts.push(goal.description);
+    }
     parts.push('');
-    parts.push(context.artifact.description);
-  }
-  parts.push('');
 
-  // Related sections (non-task sections for context, or other tasks for awareness)
-  const relatedSections = context.artifact.sections.filter(
-    s => s.id !== context.task.id
-  );
-  
-  if (relatedSections.length > 0) {
-    parts.push('### Related Sections:');
-    for (const section of relatedSections) {
-      const preview = section.content 
-        ? section.content.substring(0, 200) + (section.content.length > 200 ? '...' : '')
-        : 'No content';
-      const statusBadge = section.task_status ? ` [${section.task_status}]` : '';
-      parts.push(`- **${section.heading}**${statusBadge}: ${preview}`);
+    // Related tasks on this goal (v2)
+    if (goal.tasks && goal.tasks.length > 0) {
+      const relatedTasks = goal.tasks.filter(t => t.id !== context.task.id);
+      if (relatedTasks.length > 0) {
+        parts.push('### Related Tasks:');
+        for (const task of relatedTasks) {
+          const statusEmoji = {
+            pending: '⏳',
+            in_progress: '🔄',
+            blocked: '🚫',
+            done: '✅',
+          }[task.status] || '❓';
+          const priorityBadge = task.priority ? ` [${task.priority}]` : '';
+          parts.push(`- ${statusEmoji} **${task.title}**${priorityBadge}`);
+        }
+        parts.push('');
+      }
+    }
+
+    // Legacy: related sections (for content-based artifacts)
+    if (goal.sections && goal.sections.length > 0) {
+      const relatedSections = goal.sections.filter(s => s.id !== context.task.id);
+      if (relatedSections.length > 0) {
+        parts.push('### Related Sections:');
+        for (const section of relatedSections) {
+          const preview = section.content 
+            ? section.content.substring(0, 200) + (section.content.length > 200 ? '...' : '')
+            : 'No content';
+          const statusBadge = section.task_status ? ` [${section.task_status}]` : '';
+          parts.push(`- **${section.heading}**${statusBadge}: ${preview}`);
+        }
+        parts.push('');
+      }
     }
-    parts.push('');
   }
 
   // The task itself
   parts.push('---');
   parts.push('');
-  parts.push(`## Your Task: ${context.task.heading}`);
+  const taskTitle = context.task.title || context.task.heading;
+  parts.push(`## Your Task: ${taskTitle}`);
   
   if (context.task.priority) {
-    const priorityLabels = ['🔴 High', '🟡 Medium', '🟢 Low'];
-    parts.push(`**Priority:** ${priorityLabels[context.task.priority - 1] || 'Medium'}`);
+    const priorityEmoji = {
+      high: '🔴 High',
+      medium: '🟡 Medium',
+      low: '🟢 Low',
+    }[context.task.priority] || '🟡 Medium';
+    parts.push(`**Priority:** ${priorityEmoji}`);
+  }
+  
+  if (context.task.depends_on && context.task.depends_on.length > 0) {
+    parts.push(`**Dependencies:** ${context.task.depends_on.length} task(s)`);
   }
   parts.push('');
   
   parts.push('### Description');
-  parts.push(context.task.content || 'No additional description provided.');
+  const taskDescription = context.task.description || context.task.content;
+  parts.push(taskDescription || 'No additional description provided.');
   parts.push('');
 
   // Expected output

package/src/executor.ts

@@ -15,19 +15,32 @@ import { ContextFetcher, createContextFetcher, buildPromptWithContext, TaskFullC
 // Types
 // ============================================================================
 
+/**
+ * Task context for execution (v2)
+ */
 export interface TaskContext {
-  /** Task ID (section ID) */
-  taskId: string;
-  /** Task heading/title */
-  heading: string;
-  /** Task content/description */
-  content: string;
-  /** Parent artifact ID */
-  artifactId: string;
-  /** Parent artifact title */
+  /** Task UUID */
+  id: string;
+  /** @deprecated Use id instead */
+  taskId?: string;
+  /** Task title */
+  title: string;
+  /** @deprecated Use title instead */
+  heading?: string;
+  /** Task description */
+  description?: string;
+  /** @deprecated Use description instead */
+  content?: string;
+  /** Goal UUID this task belongs to */
+  goalId: string;
+  /** @deprecated Use goalId instead */
+  artifactId?: string;
+  /** Goal title for context */
+  goalTitle?: string;
+  /** @deprecated Use goalTitle instead */
   artifactTitle?: string;
-  /** Task priority (1=high, 2=medium, 3=low) */
-  priority?: number;
+  /** Task priority */
+  priority?: 'low' | 'medium' | 'high';
   /** Additional context */
   context?: Record<string, unknown>;
 }
@@ -138,9 +151,14 @@ export class ClaudeExecutor {
       
       if (useFullContext) {
         try {
-          fullContext = await this.contextFetcher!.fetchTaskContext(task.taskId);
+          // v2: use id, fallback to taskId for backwards compatibility
+          const taskId = task.id || task.taskId;
+          if (!taskId) {
+            throw new Error('Task ID required for context fetch');
+          }
+          fullContext = await this.contextFetcher!.fetchTaskContext(taskId);
           prompt = buildPromptWithContext(fullContext);
-          console.log('  📚 Using full context (org, project, artifact, related sections)');
+          console.log('  📚 Using full context (org, project, goal, related tasks)');
         } catch (contextError) {
           console.warn('  ⚠️  Could not fetch full context, using minimal prompt');
           console.warn(`     ${contextError instanceof Error ? contextError.message : contextError}`);
@@ -153,8 +171,9 @@ export class ClaudeExecutor {
       // Execute via Claude Code CLI
       const output = await this.runClaude(prompt);
 
-      // Extract summary if present
-      const { content, summary } = this.parseResponse(output, task.heading);
+      // Extract summary if present (v2: use title, fallback to heading)
+      const taskTitle = task.title || task.heading || 'Task';
+      const { content, summary } = this.parseResponse(output, taskTitle);
 
       return {
         success: true,
@@ -247,7 +266,7 @@ export class ClaudeExecutor {
   }
 
   /**
-   * Build the task prompt
+   * Build the task prompt (v2)
    */
   private buildTaskPrompt(task: TaskContext): string {
     const parts: string[] = [];
@@ -262,25 +281,32 @@ export class ClaudeExecutor {
     parts.push('---');
     parts.push('');
 
-    // Task header
-    parts.push(`# Task: ${task.heading}`);
+    // Task header (v2: use title, fallback to heading)
+    const taskTitle = task.title || task.heading;
+    parts.push(`# Task: ${taskTitle}`);
     parts.push('');
 
-    // Artifact context
-    if (task.artifactTitle) {
-      parts.push(`**Artifact:** ${task.artifactTitle}`);
+    // Goal context (v2: was artifact)
+    const goalTitle = task.goalTitle || task.artifactTitle;
+    if (goalTitle) {
+      parts.push(`**Goal:** ${goalTitle}`);
     }
     
-    // Priority
+    // Priority (v2: string-based)
     if (task.priority) {
-      const priorityLabels = ['High', 'Medium', 'Low'];
-      parts.push(`**Priority:** ${priorityLabels[task.priority - 1] || 'Medium'}`);
+      const priorityEmoji = {
+        high: '🔴 High',
+        medium: '🟡 Medium',
+        low: '🟢 Low',
+      }[task.priority] || '🟡 Medium';
+      parts.push(`**Priority:** ${priorityEmoji}`);
     }
     parts.push('');
 
-    // Task content
+    // Task description (v2: use description, fallback to content)
     parts.push('## Description');
-    parts.push(task.content || 'No additional description provided.');
+    const taskDescription = task.description || task.content;
+    parts.push(taskDescription || 'No additional description provided.');
     parts.push('');
 
     // Additional context

package/src/listener.ts

@@ -11,18 +11,39 @@ import EventSource from 'eventsource';
 // Types
 // ============================================================================
 
+/**
+ * Task assigned event (v2)
+ * Uses task ID and goal ID (not section_id/artifact_id)
+ */
 export interface TaskAssignedEvent {
   type: 'task_assigned';
   timestamp: string;
   data: {
-    taskId: string;
-    sectionId: string;
-    heading: string;
-    content: string;
-    artifactId: string;
+    /** Task UUID (primary identifier) */
+    id: string;
+    /** @deprecated Use id instead */
+    taskId?: string;
+    /** Goal UUID this task belongs to */
+    goalId: string;
+    /** @deprecated Use goalId instead */
+    artifactId?: string;
+    /** Task title */
+    title: string;
+    /** @deprecated Use title instead */
+    heading?: string;
+    /** Task description */
+    description?: string;
+    /** @deprecated Use description instead */
+    content?: string;
+    /** Goal title for context */
+    goalTitle?: string;
+    /** @deprecated Use goalTitle instead */
     artifactTitle?: string;
-    priority?: number;
+    /** Priority level */
+    priority?: 'low' | 'medium' | 'high';
+    /** Assigned agent ID */
     assignedTo: string;
+    /** Assignment timestamp */
     assignedAt: string;
   };
 }
@@ -242,18 +263,24 @@ export class ArtyfactsListener {
     try {
       const data = JSON.parse(event.data);
       
-      // Normalize snake_case to camelCase for task data
+      // Normalize snake_case to camelCase for task data (v2 schema)
       const rawData = data.data || data;
-      const normalizedData = rawData.task_id ? {
-        taskId: rawData.task_id,
-        sectionId: rawData.section_id,
-        artifactId: rawData.artifact_id,
-        artifactTitle: rawData.artifact_title,
-        heading: rawData.heading,
-        content: rawData.content,
+      const normalizedData = (rawData.id || rawData.task_id) ? {
+        // v2 fields (primary)
+        id: rawData.id || rawData.task_id,
+        goalId: rawData.goal_id || rawData.artifact_id,
+        goalTitle: rawData.goal_title || rawData.artifact_title,
+        title: rawData.title || rawData.heading,
+        description: rawData.description || rawData.content,
+        priority: rawData.priority,
         assignedTo: rawData.assigned_to,
         assignedAt: rawData.assigned_at,
-        priority: rawData.priority,
+        // Deprecated fields for backwards compatibility
+        taskId: rawData.id || rawData.task_id,
+        artifactId: rawData.goal_id || rawData.artifact_id,
+        artifactTitle: rawData.goal_title || rawData.artifact_title,
+        heading: rawData.title || rawData.heading,
+        content: rawData.description || rawData.content,
         ...rawData,  // Keep original fields too
       } : rawData;
 

package/src/tools/handlers.ts

@@ -225,9 +225,11 @@ export const updateAgentHandler: ToolHandler = async (args, client) => {
 };
 
 // =============================================================================
-// Task Handlers
+// Task Handlers (v2 - tasks are first-class entities)
 // =============================================================================
 
+import type { TaskQueueResponse, TaskClaimResponse, TaskCompleteResponse, InboxResponse, InboxResolveResponse } from './types';
+
 export const getTaskHandler: ToolHandler = async (args, client) => {
   try {
     const data = await client.get(`/tasks/${args.task_id}/context`);
@@ -237,36 +239,40 @@ export const getTaskHandler: ToolHandler = async (args, client) => {
   }
 };
 
+/**
+ * List tasks from the queue (v2)
+ * Uses GET /api/v1/tasks/queue - returns tasks from tasks table
+ */
 export const listTasksHandler: ToolHandler = async (args, client) => {
   try {
     const params = new URLSearchParams();
-    if (args.artifact_id) params.set('artifact_id', String(args.artifact_id));
+    if (args.goal_id) params.set('goal_id', String(args.goal_id));
     if (args.status) params.set('status', String(args.status));
     if (args.assignee) params.set('assignee', String(args.assignee));
     if (args.limit) params.set('limit', String(args.limit));
     
     const query = params.toString();
-    const path = `/tasks${query ? `?${query}` : ''}`;
-    const data = await client.get(path);
+    const path = `/tasks/queue${query ? `?${query}` : ''}`;
+    const data = await client.get<TaskQueueResponse>(path);
     return { success: true, data };
   } catch (error) {
     return { success: false, error: String(error) };
   }
 };
 
+/**
+ * Create a task (v2)
+ * Uses POST /api/v1/tasks - creates in tasks table
+ */
 export const createTaskHandler: ToolHandler = async (args, client) => {
   try {
-    const data = await client.post(`/artifacts/${args.artifact_id}/sections`, {
-      section_id: `task-${Date.now()}`,
-      heading: args.heading,
-      content: args.content,
-      type: 'task',
-      task_status: 'pending',
+    const data = await client.post('/tasks', {
+      goal_id: args.goal_id,
+      title: args.title,
+      description: args.description,
       assignee_agent_id: args.assignee,
       depends_on: args.depends_on,
-      priority: args.priority,
-      agent_id: 'system',
-      agent_name: 'System',
+      priority: args.priority || 'medium',
     });
     return { success: true, data };
   } catch (error) {
@@ -274,9 +280,27 @@ export const createTaskHandler: ToolHandler = async (args, client) => {
   }
 };
 
+/**
+ * Claim a task (v2)
+ * Uses POST /api/v1/tasks/:id/claim
+ */
+export const claimTaskHandler: ToolHandler = async (args, client) => {
+  try {
+    const data = await client.post<TaskClaimResponse>(`/tasks/${args.task_id}/claim`, {});
+    return { success: true, data };
+  } catch (error) {
+    return { success: false, error: String(error) };
+  }
+};
+
+/**
+ * Complete a task (v2)
+ * Uses POST /api/v1/tasks/:id/complete
+ * Returns unblocked_tasks for follow-up work
+ */
 export const completeTaskHandler: ToolHandler = async (args, client) => {
   try {
-    const data = await client.post(`/tasks/${args.task_id}/complete`, {
+    const data = await client.post<TaskCompleteResponse>(`/tasks/${args.task_id}/complete`, {
       output: args.output,
       summary: args.summary,
       output_url: args.output_url,
@@ -287,9 +311,13 @@ export const completeTaskHandler: ToolHandler = async (args, client) => {
   }
 };
 
+/**
+ * Block a task (v2)
+ * Uses POST /api/v1/tasks/:id/block
+ */
 export const blockTaskHandler: ToolHandler = async (args, client) => {
   try {
-    const data = await client.post(`/tasks/${args.task_id}/fail`, {
+    const data = await client.post(`/tasks/${args.task_id}/block`, {
       reason: args.reason,
       blocker_type: args.blocker_type,
     });
@@ -299,6 +327,46 @@ export const blockTaskHandler: ToolHandler = async (args, client) => {
   }
 };
 
+// =============================================================================
+// Inbox Handlers (v2)
+// =============================================================================
+
+/**
+ * List inbox items (v2)
+ * Uses GET /api/v1/inbox
+ */
+export const listInboxHandler: ToolHandler = async (args, client) => {
+  try {
+    const params = new URLSearchParams();
+    if (args.status) params.set('status', String(args.status));
+    if (args.kind) params.set('kind', String(args.kind));
+    if (args.limit) params.set('limit', String(args.limit));
+    
+    const query = params.toString();
+    const path = `/inbox${query ? `?${query}` : ''}`;
+    const data = await client.get<InboxResponse>(path);
+    return { success: true, data };
+  } catch (error) {
+    return { success: false, error: String(error) };
+  }
+};
+
+/**
+ * Resolve an inbox item (v2)
+ * Uses POST /api/v1/inbox/:id/resolve with auto-execute
+ */
+export const resolveInboxHandler: ToolHandler = async (args, client) => {
+  try {
+    const data = await client.post<InboxResolveResponse>(`/inbox/${args.inbox_id}/resolve`, {
+      decision: args.decision,
+      notes: args.notes,
+    });
+    return { success: true, data };
+  } catch (error) {
+    return { success: false, error: String(error) };
+  }
+};
+
 // =============================================================================
 // Blocker Handlers
 // =============================================================================
@@ -418,14 +486,19 @@ export const handlers: Record<string, ToolHandler> = {
   create_agent: createAgentHandler,
   update_agent: updateAgentHandler,
   
-  // Tasks
+  // Tasks (v2)
   get_task: getTaskHandler,
   list_tasks: listTasksHandler,
   create_task: createTaskHandler,
+  claim_task: claimTaskHandler,
   complete_task: completeTaskHandler,
   block_task: blockTaskHandler,
   
-  // Blockers
+  // Inbox (v2)
+  list_inbox: listInboxHandler,
+  resolve_inbox: resolveInboxHandler,
+  
+  // Blockers (legacy - kept for compatibility)
   get_blocker: getBlockerHandler,
   list_blockers: listBlockersHandler,
   create_blocker: createBlockerHandler,