agentsys 5.0.3 → 5.1.0

package/plugins/debate/lib/sources/custom-handler.js

@@ -0,0 +1,199 @@
+/**
+ * Custom Source Handler
+ * Handles follow-up questions and tool probing for custom sources
+ *
+ * @module lib/sources/custom-handler
+ */
+
+const { execFileSync } = require('child_process');
+const sourceCache = require('./source-cache');
+
+/**
+ * Validate tool name to prevent command injection
+ * Only allows alphanumeric, hyphens, and underscores
+ * @param {string} toolName - Tool name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidToolName(toolName) {
+  return /^[a-zA-Z0-9_-]+$/.test(toolName);
+}
+
+/**
+ * Source types for custom selection
+ */
+const SOURCE_TYPES = {
+  MCP: 'mcp',
+  CLI: 'cli',
+  SKILL: 'skill',
+  FILE: 'file'
+};
+
+/**
+ * Build follow-up questions for custom source
+ * Returns AskUserQuestion-compatible structure
+ * @returns {Object} Questions object for AskUserQuestion tool
+ */
+function getCustomTypeQuestion() {
+  return {
+    header: 'Source Type',
+    question: 'What type of source is this?',
+    options: [
+      { label: 'CLI Tool', description: 'Command-line tool (e.g., tea, glab, jira-cli)' },
+      { label: 'MCP Server', description: 'Model Context Protocol server' },
+      { label: 'Skill/Plugin', description: 'Claude Code skill or plugin' },
+      { label: 'File Path', description: 'Local file with tasks (markdown, JSON, etc.)' }
+    ],
+    multiSelect: false
+  };
+}
+
+/**
+ * Build name/path question based on type
+ * @param {string} type - Source type (mcp, cli, skill, file)
+ * @returns {Object} Questions object for AskUserQuestion tool
+ */
+function getCustomNameQuestion(type) {
+  const prompts = {
+    cli: { header: 'CLI Tool', question: 'What is the CLI tool name?', hint: 'e.g., tea, glab, jira' },
+    mcp: { header: 'MCP Server', question: 'What is the MCP server name?', hint: 'e.g., gitea-mcp, linear-mcp' },
+    skill: { header: 'Skill Name', question: 'What is the skill name?', hint: 'e.g., linear:list-issues' },
+    file: { header: 'File Path', question: 'What is the file path?', hint: 'e.g., ./backlog.md, /docs/tasks.json' }
+  };
+  return prompts[type] || prompts.cli;
+}
+
+/**
+ * Map user's type selection to internal type
+ * @param {string} selection - User's selection label
+ * @returns {string} Internal type (mcp, cli, skill, file)
+ */
+function mapTypeSelection(selection) {
+  const map = {
+    'CLI Tool': SOURCE_TYPES.CLI,
+    'MCP Server': SOURCE_TYPES.MCP,
+    'Skill/Plugin': SOURCE_TYPES.SKILL,
+    'File Path': SOURCE_TYPES.FILE
+  };
+  return map[selection] || SOURCE_TYPES.CLI;
+}
+
+/**
+ * Probe CLI tool for available commands
+ * @param {string} toolName - CLI tool name
+ * @returns {Object} Discovered capabilities
+ */
+function probeCLI(toolName) {
+  const capabilities = {
+    type: 'cli',
+    tool: toolName,
+    available: false,
+    features: [],
+    commands: {}
+  };
+
+  // Validate tool name to prevent command injection
+  if (!isValidToolName(toolName)) {
+    console.error(`Invalid tool name: ${toolName}`);
+    return capabilities;
+  }
+
+  try {
+    // Check if tool exists using execFileSync (prevents command injection)
+    execFileSync(toolName, ['--version'], { encoding: 'utf8', stdio: 'pipe' });
+    capabilities.available = true;
+  } catch {
+    return capabilities;
+  }
+
+  // Known CLI patterns
+  const knownPatterns = {
+    tea: {
+      features: ['issues', 'prs', 'reviews'],
+      commands: {
+        list_issues: 'tea issues list',
+        get_issue: 'tea issues view {id}',
+        create_pr: 'tea pulls create --title {title} --base {base} --head {head}',
+        list_prs: 'tea pulls list',
+        get_pr: 'tea pr {id}'
+      }
+    },
+    glab: {
+      features: ['issues', 'prs', 'ci'],
+      commands: {
+        list_issues: 'glab issue list',
+        get_issue: 'glab issue view {id}',
+        create_pr: 'glab mr create --title {title} --target-branch {base} --source-branch {head}',
+        list_prs: 'glab mr list',
+        get_pr: 'glab mr view {id}',
+        ci_status: 'glab ci status'
+      }
+    },
+    gh: {
+      features: ['issues', 'prs', 'ci'],
+      commands: {
+        list_issues: 'gh issue list',
+        get_issue: 'gh issue view {id}',
+        create_pr: 'gh pr create --title {title} --base {base} --head {head}',
+        list_prs: 'gh pr list',
+        get_pr: 'gh pr view {id}',
+        ci_status: 'gh pr checks {id}'
+      }
+    }
+  };
+
+  // Use known pattern if available
+  if (knownPatterns[toolName]) {
+    capabilities.features = knownPatterns[toolName].features;
+    capabilities.commands = knownPatterns[toolName].commands;
+    capabilities.pattern = 'known';
+  } else {
+    // Unknown tool - try to discover via help
+    capabilities.pattern = 'discovered';
+    capabilities.features = ['unknown'];
+    capabilities.commands = {
+      help: `${toolName} --help`
+    };
+  }
+
+  return capabilities;
+}
+
+/**
+ * Build complete custom source config and cache it
+ * @param {string} type - Source type
+ * @param {string} name - Tool name or path
+ * @returns {Object} Complete source configuration
+ */
+function buildCustomConfig(type, name) {
+  const config = {
+    source: 'custom',
+    type: type,
+    tool: name
+  };
+
+  // Probe capabilities for CLI tools
+  if (type === SOURCE_TYPES.CLI) {
+    const capabilities = probeCLI(name);
+    config.capabilities = capabilities;
+
+    // Cache capabilities for fast access
+    if (capabilities.available) {
+      sourceCache.saveToolCapabilities(name, capabilities);
+    }
+  }
+
+  // Save preference
+  sourceCache.savePreference(config);
+
+  return config;
+}
+
+module.exports = {
+  SOURCE_TYPES,
+  getCustomTypeQuestion,
+  getCustomNameQuestion,
+  mapTypeSelection,
+  probeCLI,
+  buildCustomConfig,
+  isValidToolName
+};

package/plugins/debate/lib/sources/policy-questions.js

@@ -0,0 +1,246 @@
+/**
+ * Policy Questions Builder
+ * Builds AskUserQuestion-ready structure with cache awareness
+ *
+ * @module lib/sources/policy-questions
+ */
+
+const sourceCache = require('./source-cache');
+const customHandler = require('./custom-handler');
+
+/**
+ * Source label mapping for proper casing
+ */
+const SOURCE_LABELS = {
+  github: 'GitHub',
+  gitlab: 'GitLab',
+  local: 'Local',
+  custom: 'Custom',
+  other: 'Other'
+};
+
+/**
+ * Get policy questions with cache-aware options
+ * Call this once - returns full question structure ready for AskUserQuestion
+ *
+ * @returns {Object} { questions: [...], cachedPreference: {...}|null }
+ */
+function getPolicyQuestions() {
+  const cached = sourceCache.getPreference();
+
+  // Build source options
+  const sourceOptions = [];
+
+  // If cached, add as first option
+  // NOTE: OpenCode enforces 30-char max on labels
+  if (cached) {
+    const cachedLabel = cached.source === 'custom'
+      ? `${cached.tool} (${cached.type})`
+      : SOURCE_LABELS[cached.source] || (cached.source.charAt(0).toUpperCase() + cached.source.slice(1));
+
+    // Truncate to fit within 30 chars: "X (last used)" where X can be max 17 chars
+    const maxBaseLen = 30 - ' (last used)'.length; // 18 chars for base
+    const truncatedLabel = cachedLabel.length > maxBaseLen
+      ? cachedLabel.substring(0, maxBaseLen - 1) + '…'
+      : cachedLabel;
+
+    sourceOptions.push({
+      label: `${truncatedLabel} (last used)`,
+      description: `Use your previous choice: ${cachedLabel}`
+    });
+  }
+
+  // Standard options
+  sourceOptions.push(
+    { label: 'GitHub Issues', description: 'Use gh CLI to list issues' },
+    { label: 'GitLab Issues', description: 'Use glab CLI to list issues' },
+    { label: 'Local tasks.md', description: 'Read from PLAN.md, tasks.md, or TODO.md' },
+    { label: 'Custom', description: 'Specify your tool: CLI, MCP, Skill, or file path' },
+    { label: 'Other', description: 'Describe your source - agent figures it out' }
+  );
+
+  return {
+    questions: [
+      {
+        header: 'Source',
+        question: 'Where should I look for tasks?',
+        options: sourceOptions,
+        multiSelect: false
+      },
+      {
+        header: 'Priority',
+        question: 'What type of tasks to prioritize?',
+        options: [
+          { label: 'All', description: 'Consider all tasks, pick by score' },
+          { label: 'Bugs', description: 'Focus on bug fixes' },
+          { label: 'Security', description: 'Security issues first' },
+          { label: 'Features', description: 'New feature development' }
+        ],
+        multiSelect: false
+      },
+      {
+        header: 'Stop Point',
+        question: 'How far should I take this task?',
+        options: [
+          { label: 'Merged', description: 'Until PR is merged to main' },
+          { label: 'PR Created', description: 'Stop after creating PR' },
+          { label: 'Implemented', description: 'Stop after local implementation' },
+          { label: 'Deployed', description: 'Deploy to staging' },
+          { label: 'Production', description: 'Full production deployment' }
+        ],
+        multiSelect: false
+      }
+    ],
+    cachedPreference: cached
+  };
+}
+
+/**
+ * Get custom source follow-up questions
+ * Call after user selects "Custom"
+ *
+ * @returns {Object} Question structure for custom type selection
+ */
+function getCustomTypeQuestions() {
+  return {
+    questions: [customHandler.getCustomTypeQuestion()]
+  };
+}
+
+/**
+ * Get custom name question based on type
+ * @param {string} type - cli, mcp, skill, or file
+ * @returns {Object} Question structure for tool/path name
+ */
+function getCustomNameQuestion(type) {
+  const q = customHandler.getCustomNameQuestion(type);
+  return {
+    questions: [{
+      header: q.header,
+      question: q.question,
+      options: [], // Free text input via "Other"
+      multiSelect: false
+    }]
+  };
+}
+
+/**
+ * Parse policy responses and build policy object
+ * Also handles caching
+ *
+ * @param {Object} responses - User's answers
+ * @param {string} responses.source - Source selection
+ * @param {string} responses.priority - Priority selection
+ * @param {string} responses.stopPoint - Stop point selection
+ * @param {Object} [responses.custom] - Custom source details (if applicable)
+ * @returns {Object} Policy object ready for workflow state
+ */
+function parseAndCachePolicy(responses) {
+  const policy = {
+    taskSource: mapSource(responses.source, responses.custom),
+    priorityFilter: mapPriority(responses.priority),
+    stoppingPoint: mapStopPoint(responses.stopPoint)
+  };
+
+  // Cache source preference (unless "other" which is ad-hoc)
+  if (policy.taskSource.source !== 'other') {
+    sourceCache.savePreference(policy.taskSource);
+  }
+
+  return policy;
+}
+
+/**
+ * Map source selection to policy value
+ */
+function mapSource(selection, customDetails) {
+  // Check if user selected cached option
+  if (selection.includes('(last used)')) {
+    return sourceCache.getPreference();
+  }
+
+  const sourceMap = {
+    'GitHub Issues': { source: 'github' },
+    'GitLab Issues': { source: 'gitlab' },
+    'Local tasks.md': { source: 'local' },
+    'Custom': null, // Handled separately
+    'Other': null   // Handled separately
+  };
+
+  if (selection === 'Custom' && customDetails) {
+    // Normalize type label to internal value (e.g., "CLI Tool" -> "cli")
+    const normalizedType = customHandler.mapTypeSelection(customDetails.type);
+    const config = customHandler.buildCustomConfig(normalizedType, customDetails.name);
+    return config;
+  }
+
+  if (selection === 'Other') {
+    return { source: 'other', description: customDetails?.description || '' };
+  }
+
+  return sourceMap[selection] || { source: 'github' };
+}
+
+/**
+ * Map priority selection to policy value
+ */
+function mapPriority(selection) {
+  const map = {
+    'All': 'all',
+    'Bugs': 'bugs',
+    'Security': 'security',
+    'Features': 'features'
+  };
+  return map[selection] || 'all';
+}
+
+/**
+ * Map stop point selection to policy value
+ */
+function mapStopPoint(selection) {
+  const map = {
+    'Merged': 'merged',
+    'PR Created': 'pr-created',
+    'Implemented': 'implemented',
+    'Deployed': 'deployed',
+    'Production': 'production'
+  };
+  return map[selection] || 'merged';
+}
+
+/**
+ * Check if user selected cached preference
+ * @param {string} selection - User's source selection
+ * @returns {boolean}
+ */
+function isUsingCached(selection) {
+  return selection.includes('(last used)');
+}
+
+/**
+ * Check if custom follow-up is needed
+ * @param {string} selection - User's source selection
+ * @returns {boolean}
+ */
+function needsCustomFollowUp(selection) {
+  return selection === 'Custom';
+}
+
+/**
+ * Check if "other" description is needed
+ * @param {string} selection - User's source selection
+ * @returns {boolean}
+ */
+function needsOtherDescription(selection) {
+  return selection === 'Other';
+}
+
+module.exports = {
+  getPolicyQuestions,
+  getCustomTypeQuestions,
+  getCustomNameQuestion,
+  parseAndCachePolicy,
+  isUsingCached,
+  needsCustomFollowUp,
+  needsOtherDescription
+};

package/plugins/debate/lib/sources/source-cache.js

@@ -0,0 +1,165 @@
+/**
+ * Source Cache
+ * File-based persistence for task source preferences
+ *
+ * State directory is platform-aware:
+ * - Claude Code: .claude/sources/
+ * - OpenCode: .opencode/sources/
+ * - Codex CLI: .codex/sources/
+ *
+ * @module lib/sources/source-cache
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getStateDir } = require('../platform/state-dir');
+const { writeJsonAtomic } = require('../utils/atomic-write');
+
+const PREFERENCE_FILE = 'preference.json';
+
+/**
+ * Get the sources directory path (platform-aware)
+ * @returns {string} Path to sources directory
+ */
+function getSourcesDir() {
+  return path.join(getStateDir(), 'sources');
+}
+
+/**
+ * Validate tool name to prevent path traversal
+ * @param {string} toolName - Tool name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidToolName(toolName) {
+  // Prevent path traversal and shell metacharacters
+  return /^[a-zA-Z0-9_-]+$/.test(toolName);
+}
+
+/**
+ * Ensure sources directory exists
+ * @returns {string} Path to sources directory
+ */
+function ensureDir() {
+  const sourcesDir = getSourcesDir();
+  if (!fs.existsSync(sourcesDir)) {
+    fs.mkdirSync(sourcesDir, { recursive: true });
+  }
+  return sourcesDir;
+}
+
+/**
+ * Get cached source preference
+ * @returns {Object|null} Preference object or null if not cached
+ * @example
+ * // Returns: { source: 'github' }
+ * // Or: { source: 'custom', type: 'cli', tool: 'tea' }
+ */
+function getPreference() {
+  const filePath = path.join(getSourcesDir(), PREFERENCE_FILE);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    console.error(`Failed to read preference file:`, err.message);
+    return null;
+  }
+}
+
+/**
+ * Save source preference
+ * @param {Object} preference - Preference object
+ * @param {string} preference.source - Source type (github, gitlab, local, custom, other)
+ * @param {string} [preference.type] - For custom: mcp, cli, skill, file
+ * @param {string} [preference.tool] - Tool name or path
+ * @param {string} [preference.description] - For other: user's free text
+ */
+function savePreference(preference) {
+  ensureDir();
+  const filePath = path.join(getSourcesDir(), PREFERENCE_FILE);
+  writeJsonAtomic(filePath, {
+    ...preference,
+    savedAt: new Date().toISOString()
+  });
+}
+
+/**
+ * Get cached tool capabilities (for custom sources)
+ * @param {string} toolName - Tool identifier (e.g., 'tea', 'glab')
+ * @returns {Object|null} Capabilities object or null
+ */
+function getToolCapabilities(toolName) {
+  // Prevent path traversal
+  if (!isValidToolName(toolName)) {
+    console.error(`Invalid tool name: ${toolName}`);
+    return null;
+  }
+  const filePath = path.join(getSourcesDir(), `${toolName}.json`);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    console.error(`Failed to read tool capabilities for ${toolName}:`, err.message);
+    return null;
+  }
+}
+
+/**
+ * Save tool capabilities after discovery
+ * @param {string} toolName - Tool identifier
+ * @param {Object} capabilities - Discovered capabilities
+ * @param {string[]} capabilities.features - Available features (issues, prs, ci)
+ * @param {Object} capabilities.commands - Command mappings
+ */
+function saveToolCapabilities(toolName, capabilities) {
+  // Prevent path traversal
+  if (!isValidToolName(toolName)) {
+    console.error(`Invalid tool name: ${toolName}`);
+    return;
+  }
+  ensureDir();
+  const filePath = path.join(getSourcesDir(), `${toolName}.json`);
+  fs.writeFileSync(filePath, JSON.stringify({
+    ...capabilities,
+    discoveredAt: new Date().toISOString()
+  }, null, 2));
+}
+
+/**
+ * Clear all cached preferences
+ */
+function clearCache() {
+  const sourcesDir = getSourcesDir();
+  if (fs.existsSync(sourcesDir)) {
+    const files = fs.readdirSync(sourcesDir);
+    for (const file of files) {
+      const filePath = path.join(sourcesDir, file);
+      const stats = fs.statSync(filePath);
+      if (stats.isFile()) {
+        fs.unlinkSync(filePath);
+      }
+    }
+  }
+}
+
+/**
+ * Check if preference matches a specific source
+ * @param {string} source - Source to check
+ * @returns {boolean} True if preference matches
+ */
+function isPreferred(source) {
+  const pref = getPreference();
+  return pref?.source === source;
+}
+
+module.exports = {
+  getPreference,
+  savePreference,
+  getToolCapabilities,
+  saveToolCapabilities,
+  clearCache,
+  isPreferred
+};