@artyfacts/claude 1.2.3 → 1.3.0

package/src/tools/registry.ts

@@ -0,0 +1,780 @@
+/**
+ * Artyfacts Tools Registry
+ * 
+ * Defines all tools available to agents for interacting with Artyfacts.
+ * Tools are mapped to permissions - agents only get tools they have permission for.
+ */
+
+import { Tool, ToolHandler, ToolSchema } from './types';
+
+// =============================================================================
+// Tool Schemas (JSON Schema format for Claude)
+// =============================================================================
+
+const schemas: Record<string, ToolSchema> = {
+  // ---------------------------------------------------------------------------
+  // Section Tools
+  // ---------------------------------------------------------------------------
+  get_section: {
+    name: 'get_section',
+    description: 'Read a section by ID. Returns the section content, type, and metadata.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        section_id: {
+          type: 'string',
+          description: 'The UUID of the section to read',
+        },
+      },
+      required: ['section_id'],
+    },
+  },
+
+  list_sections: {
+    name: 'list_sections',
+    description: 'List all sections of an artifact. Returns sections in order with their content and metadata.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        artifact_id: {
+          type: 'string',
+          description: 'The UUID of the artifact',
+        },
+        type: {
+          type: 'string',
+          enum: ['content', 'task', 'decision'],
+          description: 'Optional: filter by section type',
+        },
+      },
+      required: ['artifact_id'],
+    },
+  },
+
+  create_section: {
+    name: 'create_section',
+    description: 'Add a new section to an artifact. Use for documenting analysis, recommendations, or any structured content.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        artifact_id: {
+          type: 'string',
+          description: 'The UUID of the artifact to add the section to',
+        },
+        heading: {
+          type: 'string',
+          description: 'The section heading/title',
+        },
+        content: {
+          type: 'string',
+          description: 'The section content (supports Markdown)',
+        },
+        type: {
+          type: 'string',
+          enum: ['content', 'task', 'decision'],
+          default: 'content',
+          description: 'Section type. Use "content" for documentation, "task" for actionable items, "decision" for choices needing approval.',
+        },
+        position: {
+          type: 'number',
+          description: 'Optional: position in the section order (0-indexed). Defaults to end.',
+        },
+      },
+      required: ['artifact_id', 'heading', 'content'],
+    },
+  },
+
+  update_section: {
+    name: 'update_section',
+    description: 'Update an existing section content or metadata.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        section_id: {
+          type: 'string',
+          description: 'The UUID of the section to update',
+        },
+        heading: {
+          type: 'string',
+          description: 'New heading (optional)',
+        },
+        content: {
+          type: 'string',
+          description: 'New content (optional)',
+        },
+      },
+      required: ['section_id'],
+    },
+  },
+
+  delete_section: {
+    name: 'delete_section',
+    description: 'Remove a section from an artifact. Use with caution.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        section_id: {
+          type: 'string',
+          description: 'The UUID of the section to delete',
+        },
+      },
+      required: ['section_id'],
+    },
+  },
+
+  // ---------------------------------------------------------------------------
+  // Artifact Tools
+  // ---------------------------------------------------------------------------
+  get_artifact: {
+    name: 'get_artifact',
+    description: 'Read an artifact by ID. Returns title, content, status, and metadata.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        artifact_id: {
+          type: 'string',
+          description: 'The UUID of the artifact',
+        },
+        include_sections: {
+          type: 'boolean',
+          default: false,
+          description: 'Whether to include all sections in the response',
+        },
+      },
+      required: ['artifact_id'],
+    },
+  },
+
+  list_artifacts: {
+    name: 'list_artifacts',
+    description: 'List artifacts with optional filters. Returns summaries, not full content.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          enum: ['goal', 'spec', 'doc', 'research', 'report'],
+          description: 'Filter by artifact type',
+        },
+        status: {
+          type: 'string',
+          enum: ['draft', 'active', 'completed', 'archived'],
+          description: 'Filter by status',
+        },
+        parent_id: {
+          type: 'string',
+          description: 'Filter by parent artifact ID',
+        },
+        limit: {
+          type: 'number',
+          default: 20,
+          description: 'Max results to return',
+        },
+      },
+      required: [],
+    },
+  },
+
+  search_artifacts: {
+    name: 'search_artifacts',
+    description: 'Search artifacts by text query. Returns matching artifacts ranked by relevance.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query text',
+        },
+        type: {
+          type: 'string',
+          enum: ['goal', 'spec', 'doc', 'research', 'report'],
+          description: 'Optional: filter by type',
+        },
+        limit: {
+          type: 'number',
+          default: 10,
+          description: 'Max results',
+        },
+      },
+      required: ['query'],
+    },
+  },
+
+  create_artifact: {
+    name: 'create_artifact',
+    description: 'Create a new artifact (document, spec, goal, etc.).',
+    input_schema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: 'Artifact title',
+        },
+        type: {
+          type: 'string',
+          enum: ['goal', 'spec', 'doc', 'research', 'report', 'runbook'],
+          description: 'Artifact type',
+        },
+        content: {
+          type: 'string',
+          description: 'Initial content (Markdown)',
+        },
+        summary: {
+          type: 'string',
+          description: 'Brief summary/description',
+        },
+        parent_id: {
+          type: 'string',
+          description: 'Optional: parent artifact ID for hierarchy',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional: tags for categorization',
+        },
+      },
+      required: ['title', 'type'],
+    },
+  },
+
+  update_artifact: {
+    name: 'update_artifact',
+    description: 'Update artifact metadata (title, status, summary).',
+    input_schema: {
+      type: 'object',
+      properties: {
+        artifact_id: {
+          type: 'string',
+          description: 'The UUID of the artifact',
+        },
+        title: {
+          type: 'string',
+          description: 'New title',
+        },
+        summary: {
+          type: 'string',
+          description: 'New summary',
+        },
+        status: {
+          type: 'string',
+          enum: ['draft', 'active', 'completed', 'archived'],
+          description: 'New status',
+        },
+      },
+      required: ['artifact_id'],
+    },
+  },
+
+  link_artifacts: {
+    name: 'link_artifacts',
+    description: 'Create a parent-child relationship between artifacts.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        parent_id: {
+          type: 'string',
+          description: 'The parent artifact UUID',
+        },
+        child_id: {
+          type: 'string',
+          description: 'The child artifact UUID',
+        },
+      },
+      required: ['parent_id', 'child_id'],
+    },
+  },
+
+  // ---------------------------------------------------------------------------
+  // Agent Tools
+  // ---------------------------------------------------------------------------
+  get_agent: {
+    name: 'get_agent',
+    description: 'Read agent details including role, capabilities, and permissions.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        agent_id: {
+          type: 'string',
+          description: 'The agent ID (slug or UUID)',
+        },
+      },
+      required: ['agent_id'],
+    },
+  },
+
+  list_agents: {
+    name: 'list_agents',
+    description: 'List all agents in the organization.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        role: {
+          type: 'string',
+          description: 'Optional: filter by role',
+        },
+        status: {
+          type: 'string',
+          enum: ['active', 'inactive'],
+          description: 'Optional: filter by status',
+        },
+      },
+      required: [],
+    },
+  },
+
+  create_agent: {
+    name: 'create_agent',
+    description: 'Create a new AI agent with specified role, capabilities, and system prompt.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Agent ID/slug (lowercase, hyphens, e.g., "content-writer")',
+        },
+        name: {
+          type: 'string',
+          description: 'Display name (e.g., "Content Writer")',
+        },
+        role: {
+          type: 'string',
+          description: 'Agent role/title (e.g., "Senior Content Writer")',
+        },
+        description: {
+          type: 'string',
+          description: 'Brief description of what this agent does',
+        },
+        system_prompt: {
+          type: 'string',
+          description: 'System prompt that defines agent behavior and personality',
+        },
+        capabilities: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of capabilities (e.g., ["content-creation", "research"])',
+        },
+        permissions: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of permissions (e.g., ["sections:write", "artifacts:read"])',
+        },
+        model: {
+          type: 'string',
+          description: 'Optional: preferred model (defaults to org default)',
+        },
+      },
+      required: ['id', 'name', 'role', 'description', 'system_prompt'],
+    },
+  },
+
+  update_agent: {
+    name: 'update_agent',
+    description: 'Update an existing agent configuration.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        agent_id: {
+          type: 'string',
+          description: 'The agent ID to update',
+        },
+        name: {
+          type: 'string',
+          description: 'New display name',
+        },
+        role: {
+          type: 'string',
+          description: 'New role',
+        },
+        description: {
+          type: 'string',
+          description: 'New description',
+        },
+        system_prompt: {
+          type: 'string',
+          description: 'New system prompt',
+        },
+        capabilities: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'New capabilities list',
+        },
+        permissions: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'New permissions list',
+        },
+        status: {
+          type: 'string',
+          enum: ['active', 'inactive'],
+          description: 'Agent status',
+        },
+      },
+      required: ['agent_id'],
+    },
+  },
+
+  // ---------------------------------------------------------------------------
+  // Task Tools
+  // ---------------------------------------------------------------------------
+  get_task: {
+    name: 'get_task',
+    description: 'Read task details including status, content, and dependencies.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'string',
+          description: 'The task UUID or section_id',
+        },
+      },
+      required: ['task_id'],
+    },
+  },
+
+  list_tasks: {
+    name: 'list_tasks',
+    description: 'List tasks with optional filters.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        artifact_id: {
+          type: 'string',
+          description: 'Filter by artifact',
+        },
+        status: {
+          type: 'string',
+          enum: ['pending', 'in_progress', 'blocked', 'done'],
+          description: 'Filter by status',
+        },
+        assignee: {
+          type: 'string',
+          description: 'Filter by assigned agent',
+        },
+        limit: {
+          type: 'number',
+          default: 20,
+          description: 'Max results',
+        },
+      },
+      required: [],
+    },
+  },
+
+  create_task: {
+    name: 'create_task',
+    description: 'Create a new task on an artifact.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        artifact_id: {
+          type: 'string',
+          description: 'The artifact to add the task to',
+        },
+        heading: {
+          type: 'string',
+          description: 'Task title/heading',
+        },
+        content: {
+          type: 'string',
+          description: 'Task description and requirements',
+        },
+        assignee: {
+          type: 'string',
+          description: 'Optional: agent ID to assign to',
+        },
+        depends_on: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional: section_ids of tasks this depends on',
+        },
+        priority: {
+          type: 'number',
+          enum: [1, 2, 3],
+          description: 'Optional: priority (1=high, 2=medium, 3=low)',
+        },
+      },
+      required: ['artifact_id', 'heading', 'content'],
+    },
+  },
+
+  complete_task: {
+    name: 'complete_task',
+    description: 'Mark a task as completed with output.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'string',
+          description: 'The task UUID or section_id',
+        },
+        output: {
+          type: 'string',
+          description: 'The task output/deliverable',
+        },
+        summary: {
+          type: 'string',
+          description: 'Brief summary of what was accomplished',
+        },
+        output_url: {
+          type: 'string',
+          description: 'Optional: URL to output (PR, doc, etc.)',
+        },
+      },
+      required: ['task_id', 'summary'],
+    },
+  },
+
+  block_task: {
+    name: 'block_task',
+    description: 'Mark a task as blocked with a reason.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'string',
+          description: 'The task UUID or section_id',
+        },
+        reason: {
+          type: 'string',
+          description: 'Why the task is blocked',
+        },
+        blocker_type: {
+          type: 'string',
+          enum: ['dependency', 'approval', 'information', 'technical'],
+          description: 'Type of blocker',
+        },
+      },
+      required: ['task_id', 'reason'],
+    },
+  },
+
+  // ---------------------------------------------------------------------------
+  // Blocker Tools
+  // ---------------------------------------------------------------------------
+  get_blocker: {
+    name: 'get_blocker',
+    description: 'Read blocker/decision details.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        blocker_id: {
+          type: 'string',
+          description: 'The blocker UUID',
+        },
+      },
+      required: ['blocker_id'],
+    },
+  },
+
+  list_blockers: {
+    name: 'list_blockers',
+    description: 'List blockers/decisions with optional filters.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          enum: ['pending', 'resolved'],
+          description: 'Filter by status',
+        },
+        artifact_id: {
+          type: 'string',
+          description: 'Filter by artifact',
+        },
+        kind: {
+          type: 'string',
+          enum: ['decision', 'approval', 'information'],
+          description: 'Filter by blocker type',
+        },
+      },
+      required: [],
+    },
+  },
+
+  create_blocker: {
+    name: 'create_blocker',
+    description: 'Create a blocker/decision that needs human input.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: 'Blocker title/question',
+        },
+        description: {
+          type: 'string',
+          description: 'Detailed description of what needs to be decided',
+        },
+        kind: {
+          type: 'string',
+          enum: ['decision', 'approval', 'information'],
+          description: 'Type of blocker',
+        },
+        options: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              description: { type: 'string' },
+            },
+          },
+          description: 'For decisions: the options to choose from',
+        },
+        artifact_id: {
+          type: 'string',
+          description: 'Optional: related artifact',
+        },
+        task_id: {
+          type: 'string',
+          description: 'Optional: related task (will block it)',
+        },
+      },
+      required: ['title', 'description', 'kind'],
+    },
+  },
+
+  resolve_blocker: {
+    name: 'resolve_blocker',
+    description: 'Resolve a blocker with a decision (usually done by humans, but agents can too if permitted).',
+    input_schema: {
+      type: 'object',
+      properties: {
+        blocker_id: {
+          type: 'string',
+          description: 'The blocker UUID',
+        },
+        decision: {
+          type: 'string',
+          description: 'The decision/resolution',
+        },
+        notes: {
+          type: 'string',
+          description: 'Optional: additional context',
+        },
+      },
+      required: ['blocker_id', 'decision'],
+    },
+  },
+
+  // ---------------------------------------------------------------------------
+  // Organization Tools
+  // ---------------------------------------------------------------------------
+  get_org_context: {
+    name: 'get_org_context',
+    description: 'Get organization context including name, industry, size, and preferences.',
+    input_schema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+
+  get_project: {
+    name: 'get_project',
+    description: 'Get project details.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        project_id: {
+          type: 'string',
+          description: 'Project UUID or slug',
+        },
+      },
+      required: ['project_id'],
+    },
+  },
+
+  list_projects: {
+    name: 'list_projects',
+    description: 'List all projects in the organization.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          enum: ['active', 'archived'],
+          description: 'Filter by status',
+        },
+      },
+      required: [],
+    },
+  },
+};
+
+// =============================================================================
+// Permission Mapping
+// =============================================================================
+
+export const permissionToTools: Record<string, string[]> = {
+  'sections:read': ['get_section', 'list_sections'],
+  'sections:write': ['create_section', 'update_section', 'delete_section'],
+  'artifacts:read': ['get_artifact', 'list_artifacts', 'search_artifacts'],
+  'artifacts:write': ['create_artifact', 'update_artifact', 'link_artifacts'],
+  'agents:read': ['get_agent', 'list_agents'],
+  'agents:write': ['create_agent', 'update_agent'],
+  'tasks:read': ['get_task', 'list_tasks'],
+  'tasks:write': ['create_task', 'complete_task', 'block_task'],
+  'blockers:read': ['get_blocker', 'list_blockers'],
+  'blockers:write': ['create_blocker', 'resolve_blocker'],
+  'org:read': ['get_org_context', 'get_project', 'list_projects'],
+};
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+/**
+ * Get all tool schemas
+ */
+export function getAllToolSchemas(): ToolSchema[] {
+  return Object.values(schemas);
+}
+
+/**
+ * Get tool schema by name
+ */
+export function getToolSchema(name: string): ToolSchema | undefined {
+  return schemas[name];
+}
+
+/**
+ * Get tools available for a set of permissions
+ */
+export function getToolsForPermissions(permissions: string[]): ToolSchema[] {
+  const toolNames = new Set<string>();
+  
+  for (const permission of permissions) {
+    const tools = permissionToTools[permission] || [];
+    tools.forEach(t => toolNames.add(t));
+  }
+  
+  return Array.from(toolNames)
+    .map(name => schemas[name])
+    .filter(Boolean);
+}
+
+/**
+ * Check if a tool is allowed for a set of permissions
+ */
+export function isToolAllowed(toolName: string, permissions: string[]): boolean {
+  for (const permission of permissions) {
+    if (permissionToTools[permission]?.includes(toolName)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Get the permission required for a tool
+ */
+export function getRequiredPermission(toolName: string): string | undefined {
+  for (const [permission, tools] of Object.entries(permissionToTools)) {
+    if (tools.includes(toolName)) {
+      return permission;
+    }
+  }
+  return undefined;
+}
+
+export { schemas };