@useconductor/conductor 1.0.0 → 1.0.1

package/docs/plugin-sdk.md

@@ -0,0 +1,212 @@
+# Plugin SDK
+
+Create your own plugins for Conductor.
+
+## Quick Start
+
+```typescript
+import { Plugin, PluginTool } from '@useconductor/conductor/plugins';
+
+export class MyPlugin implements Plugin {
+  name = 'my-plugin';
+  description = 'My custom plugin';
+  version = '1.0.0';
+
+  async initialize(conductor) {
+    // Setup - e.g., connect to API, load config
+  }
+
+  isConfigured(): boolean {
+    // Return true if plugin has required credentials
+    return true;
+  }
+
+  getTools(): PluginTool[] {
+    return [
+      {
+        name: 'my_plugin_action',
+        description: 'Does something useful',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            input: { type: 'string', description: 'Input description' }
+          },
+          required: ['input']
+        },
+        handler: async (args) => {
+          const result = await this.doSomething(args.input);
+          return { result };
+        }
+      }
+    ];
+  }
+
+  // Optional: proactive context for AI
+  async getContext() {
+    return null;
+  }
+}
+```
+
+## Full Example
+
+```typescript
+import { Plugin, PluginTool, ToolContext } from '@useconductor/conductor/plugins';
+
+export class GitHub IssuesPlugin implements Plugin {
+  name = 'github-issues';
+  description = 'Manage GitHub issues';
+  version = '1.0.0';
+  
+  private apiKey?: string;
+  private owner?: string;
+  private repo?: string;
+
+  async initialize(conductor) {
+    const config = conductor.getConfig();
+    this.apiKey = await conductor.getKeychain().get('github', 'token');
+    
+    const prefs = config.get('plugins.github-issues');
+    this.owner = prefs?.owner;
+    this.repo = prefs?.repo;
+  }
+
+  isConfigured(): boolean {
+    return !!this.apiKey && !!this.owner && !!this.repo;
+  }
+
+  getTools(): PluginTool[] {
+    return [
+      {
+        name: 'github_issues_list',
+        description: 'List GitHub issues',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            state: { 
+              type: 'string', 
+              enum: ['open', 'closed', 'all'],
+              description: 'Issue state'
+            },
+            limit: {
+              type: 'number',
+              description: 'Max issues to return'
+            }
+          }
+        },
+        handler: async (args, context) => {
+          return this.listIssues(args.state, args.limit);
+        }
+      },
+      {
+        name: 'github_issues_create',
+        description: 'Create a GitHub issue',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            body: { type: 'string' },
+            labels: { type: 'array', items: { type: 'string' } }
+          },
+          required: ['title']
+        },
+        handler: async (args) => {
+          return this.createIssue(args.title, args.body, args.labels);
+        }
+      }
+    ];
+  }
+
+  private async listIssues(state: string = 'open', limit: number = 10) {
+    // Implementation
+  }
+
+  private async createIssue(title: string, body?: string, labels?: string[]) {
+    // Implementation
+  }
+}
+```
+
+## Config Schema
+
+For `conductor plugins setup <name>`:
+
+```typescript
+getConfigSchema() {
+  return {
+    fields: {
+      owner: {
+        label: 'GitHub Owner',
+        type: 'string',
+        required: true,
+        description: 'Organization or username'
+      },
+      repo: {
+        label: 'Repository',
+        type: 'string', 
+        required: true
+      },
+      token: {
+        label: 'GitHub Token',
+        type: 'password',
+        secret: true,
+        description: 'Personal access token'
+      }
+    }
+  };
+}
+```
+
+## Tool Handler Signature
+
+```typescript
+handler: async (
+  args: Record<string, unknown>,  // Parsed input
+  context: ToolContext            // Execution context
+) => {
+  // args = parsed and validated input
+  // context.conductor = Conductor instance
+  // context.user = user info (in multi-user mode)
+  
+  return { /* result */ };
+}
+```
+
+## Publishing
+
+```bash
+# Build
+npm run build
+
+# Publish to npm
+npm publish
+
+# Or submit to Conductor marketplace
+conductor plugins publish ./dist
+```
+
+## Types
+
+```typescript
+interface Plugin {
+  name: string;
+  description: string;
+  version: string;
+  
+  initialize(conductor: Conductor): Promise<void>;
+  isConfigured(): boolean;
+  getTools(): PluginTool[];
+  
+  // Optional
+  getConfigSchema?(): PluginConfigSchema;
+  getContext?(): Promise<string | null>;
+}
+
+interface PluginTool {
+  name: string;
+  description: string;
+  inputSchema: object;
+  handler: (args: any, context: ToolContext) => Promise<any>;
+  requiresApproval?: boolean;
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@useconductor/conductor",
-  "version": "1.0.0",
-  "description": "The AI Tool Hub — One MCP server. 100+ tools. Every AI agent.",
+  "version": "1.0.1",
+  "description": "The AI Tool Hub — One MCP server. 255 tools. Every AI agent.",
   "main": "dist/index.js",
   "bin": {
     "conductor": "./dist/cli/index.js"
@@ -19,14 +19,16 @@
     "format": "prettier --write \"src/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "publish": "npm run build && npm publish",
+    "publish:beta": "npm run build && npm publish --tag beta"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.12.0"
   },
   "keywords": [
     "mcp",
@@ -44,8 +46,6 @@
   "license": "Apache-2.0",
   "type": "module",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.74.0",
-    "@google/generative-ai": "^0.24.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@octokit/rest": "^22.0.1",
     "@slack/bolt": "^4.6.0",
@@ -59,7 +59,6 @@
     "inquirer": "^13.2.5",
     "mathjs": "^15.1.1",
     "open": "^11.0.0",
-    "openai": "^6.22.0",
     "ora": "^9.3.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
@@ -84,7 +83,11 @@
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitepress": "^1.6.4",
     "vitest": "^4.1.2"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.86.1",
+    "@google/generative-ai": "^0.24.1",
+    "openai": "^6.34.0"
   }
 }

package/src/cli/commands/audit.ts

@@ -0,0 +1,318 @@
+/**
+ * conductor audit — query and verify the tamper-evident audit log.
+ *
+ * Commands:
+ *   conductor audit list   — filter and display log entries
+ *   conductor audit verify — verify SHA-256 chain integrity
+ *   conductor audit tail   — stream the log in real time
+ *   conductor audit export — export entries to JSON or NDJSON
+ *   conductor audit stats  — show summary statistics
+ *   conductor audit rotate — manually rotate the current log file
+ */
+
+import fs from 'fs/promises';
+import { createReadStream } from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { AuditLogger } from '../../core/audit.js';
+import type { AuditEntry } from '../../core/audit.js';
+import type { Conductor } from '../../core/conductor.js';
+
+function getAuditDir(conductor: Conductor): string {
+  return path.join(conductor.getConfig().getConfigDir(), 'audit');
+}
+
+function getAuditFile(conductor: Conductor): string {
+  return path.join(getAuditDir(conductor), 'audit.log');
+}
+
+/** Read all entries from all audit log files, newest files last. */
+async function readAllEntries(conductor: Conductor): Promise<AuditEntry[]> {
+  const dir = getAuditDir(conductor);
+  const entries: AuditEntry[] = [];
+
+  let files: string[];
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const logFiles = files.filter((f) => f.endsWith('.log')).sort();
+
+  for (const file of logFiles) {
+    const content = await fs.readFile(path.join(dir, file), 'utf-8').catch(() => '');
+    for (const line of content.split('\n').filter((l) => l.trim())) {
+      try {
+        entries.push(JSON.parse(line) as AuditEntry);
+      } catch {
+        // skip malformed lines
+      }
+    }
+  }
+
+  return entries;
+}
+
+function formatEntry(e: AuditEntry): string {
+  const time = e.timestamp.replace('T', ' ').replace(/\.\d+Z$/, '');
+  const icon = e.result === 'success' ? '✓' : e.result === 'failure' ? '✗' : e.result === 'denied' ? '⊘' : '⏱';
+  return `  ${icon} ${time}  ${e.actor.padEnd(12)} ${e.action.padEnd(16)} ${e.resource}`;
+}
+
+// ── list ──────────────────────────────────────────────────────────────────────
+
+export async function auditList(
+  conductor: Conductor,
+  opts: {
+    actor?: string;
+    action?: string;
+    tool?: string;
+    result?: string;
+    since?: string;
+    until?: string;
+    limit?: string;
+    json?: boolean;
+  },
+): Promise<void> {
+  let entries = await readAllEntries(conductor);
+
+  if (opts.actor) entries = entries.filter((e) => e.actor === opts.actor);
+  if (opts.action) entries = entries.filter((e) => e.action === opts.action);
+  if (opts.tool) entries = entries.filter((e) => e.resource === opts.tool);
+  if (opts.result) entries = entries.filter((e) => e.result === opts.result);
+  if (opts.since) entries = entries.filter((e) => e.timestamp >= opts.since!);
+  if (opts.until) entries = entries.filter((e) => e.timestamp <= opts.until!);
+
+  const limit = opts.limit ? parseInt(opts.limit, 10) : 100;
+  entries = entries.slice(-limit);
+
+  if (entries.length === 0) {
+    console.log('\n  No audit entries found.\n');
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(`  📋 Audit Log (${entries.length} entries)\n`);
+  console.log(
+    `  ${'RESULT'.padEnd(3)} ${'TIMESTAMP'.padEnd(19)}  ${'ACTOR'.padEnd(12)} ${'ACTION'.padEnd(16)} RESOURCE`,
+  );
+  console.log('  ' + '─'.repeat(80));
+  for (const e of entries) {
+    console.log(formatEntry(e));
+  }
+  console.log('');
+}
+
+// ── verify ────────────────────────────────────────────────────────────────────
+
+export async function auditVerify(conductor: Conductor, opts: { json?: boolean }): Promise<void> {
+  const logger = new AuditLogger(conductor.getConfig().getConfigDir(), { flushIntervalMs: 50000 });
+  try {
+    const { valid, brokenAt } = await logger.verifyIntegrity();
+
+    if (opts.json) {
+      console.log(JSON.stringify({ valid, brokenAt }));
+      return;
+    }
+
+    console.log('');
+    if (valid) {
+      console.log('  ✅ Audit log integrity verified — no tampering detected.\n');
+    } else {
+      console.log(`  ❌ Integrity check FAILED — chain broken at: ${brokenAt}\n`);
+      console.log('  The audit log may have been tampered with. Contact your security team.\n');
+      process.exit(1);
+    }
+  } finally {
+    await logger.close();
+  }
+}
+
+// ── tail ──────────────────────────────────────────────────────────────────────
+
+export async function auditTail(conductor: Conductor, opts: { json?: boolean; lines?: string }): Promise<void> {
+  const logFile = getAuditFile(conductor);
+  const initialLines = parseInt(opts.lines || '20', 10);
+
+  // Show last N lines from existing file
+  try {
+    const content = await fs.readFile(logFile, 'utf-8');
+    const lines = content.split('\n').filter((l) => l.trim());
+    const recent = lines.slice(-initialLines);
+
+    console.log('');
+    for (const line of recent) {
+      try {
+        const e = JSON.parse(line) as AuditEntry;
+        if (opts.json) {
+          console.log(JSON.stringify(e));
+        } else {
+          console.log(formatEntry(e));
+        }
+      } catch {
+        // skip
+      }
+    }
+  } catch {
+    console.log('\n  No audit log found yet.\n');
+  }
+
+  // Watch for new lines
+  console.log('\n  Watching for new entries (Ctrl+C to stop)...\n');
+
+  let fileSize = 0;
+  try {
+    const stat = await fs.stat(logFile);
+    fileSize = stat.size;
+  } catch {
+    fileSize = 0;
+  }
+
+  const watcher = setInterval(async () => {
+    try {
+      const stat = await fs.stat(logFile);
+      if (stat.size > fileSize) {
+        const stream = createReadStream(logFile, { start: fileSize });
+        const rl = readline.createInterface({ input: stream });
+        rl.on('line', (line) => {
+          if (!line.trim()) return;
+          try {
+            const e = JSON.parse(line) as AuditEntry;
+            if (opts.json) {
+              console.log(JSON.stringify(e));
+            } else {
+              console.log(formatEntry(e));
+            }
+          } catch {
+            // skip
+          }
+        });
+        fileSize = stat.size;
+      }
+    } catch {
+      // file not yet created
+    }
+  }, 500);
+
+  process.on('SIGINT', () => {
+    clearInterval(watcher);
+    console.log('\n');
+    process.exit(0);
+  });
+
+  // Keep alive
+  await new Promise(() => {});
+}
+
+// ── export ────────────────────────────────────────────────────────────────────
+
+export async function auditExport(
+  conductor: Conductor,
+  opts: {
+    output?: string;
+    format?: string;
+    since?: string;
+    until?: string;
+  },
+): Promise<void> {
+  let entries = await readAllEntries(conductor);
+
+  if (opts.since) entries = entries.filter((e) => e.timestamp >= opts.since!);
+  if (opts.until) entries = entries.filter((e) => e.timestamp <= opts.until!);
+
+  const format = opts.format || 'json';
+  const output = opts.output || `-`;
+
+  let content: string;
+  if (format === 'ndjson') {
+    content = entries.map((e) => JSON.stringify(e)).join('\n') + '\n';
+  } else {
+    content = JSON.stringify(entries, null, 2) + '\n';
+  }
+
+  if (output === '-') {
+    process.stdout.write(content);
+  } else {
+    await fs.writeFile(output, content, 'utf-8');
+    console.log(`\n  ✅ Exported ${entries.length} entries to: ${output}\n`);
+  }
+}
+
+// ── stats ─────────────────────────────────────────────────────────────────────
+
+export async function auditStats(conductor: Conductor, opts: { json?: boolean }): Promise<void> {
+  const entries = await readAllEntries(conductor);
+
+  if (entries.length === 0) {
+    console.log('\n  No audit entries found.\n');
+    return;
+  }
+
+  const byAction: Record<string, number> = {};
+  const byActor: Record<string, number> = {};
+  const byResult: Record<string, number> = {};
+
+  for (const e of entries) {
+    byAction[e.action] = (byAction[e.action] || 0) + 1;
+    byActor[e.actor] = (byActor[e.actor] || 0) + 1;
+    byResult[e.result] = (byResult[e.result] || 0) + 1;
+  }
+
+  const stats = {
+    total: entries.length,
+    first: entries[0]?.timestamp,
+    last: entries[entries.length - 1]?.timestamp,
+    by_action: byAction,
+    by_actor: byActor,
+    by_result: byResult,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(`  📊 Audit Log Statistics\n`);
+  console.log(`  Total entries:  ${stats.total}`);
+  console.log(`  First entry:    ${stats.first}`);
+  console.log(`  Last entry:     ${stats.last}`);
+  console.log('');
+  console.log('  By result:');
+  for (const [k, v] of Object.entries(byResult).sort((a, b) => b[1] - a[1])) {
+    console.log(`    ${k.padEnd(12)} ${v}`);
+  }
+  console.log('');
+  console.log('  By action (top 10):');
+  for (const [k, v] of Object.entries(byAction)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)) {
+    console.log(`    ${k.padEnd(20)} ${v}`);
+  }
+  console.log('');
+}
+
+// ── rotate ────────────────────────────────────────────────────────────────────
+
+export async function auditRotate(conductor: Conductor): Promise<void> {
+  const logFile = getAuditFile(conductor);
+
+  try {
+    const stat = await fs.stat(logFile);
+    if (stat.size === 0) {
+      console.log('\n  Log file is empty — nothing to rotate.\n');
+      return;
+    }
+    const rotated = `${logFile}.${Date.now()}.bak`;
+    await fs.rename(logFile, rotated);
+    console.log(`\n  ✅ Rotated audit log to: ${path.basename(rotated)}\n`);
+  } catch {
+    console.log('\n  No audit log to rotate.\n');
+  }
+}

package/src/cli/commands/circuit.ts

@@ -0,0 +1,63 @@
+/**
+ * conductor circuit — view and manage circuit breaker state.
+ *
+ * Commands:
+ *   conductor circuit list   — show state of all circuit breakers
+ *   conductor circuit reset  — reset a specific circuit to closed state
+ */
+
+import type { Conductor } from '../../core/conductor.js';
+
+export async function circuitList(conductor: Conductor, opts: { json?: boolean }): Promise<void> {
+  await conductor.initialize();
+
+  // Circuit breaker state is held in the running MCP server's memory.
+  // If we're not in the server process, we read the persisted health state
+  // from the health check endpoint instead.
+  try {
+    const { HealthChecker } = await import('../../core/health.js');
+    const checker = new HealthChecker();
+    const report = await checker.detailed('0');
+
+    const metrics = report.metrics;
+
+    if (opts.json) {
+      console.log(JSON.stringify({ open_circuits: metrics?.openCircuits ?? 0 }, null, 2));
+      return;
+    }
+
+    console.log('');
+    console.log('  ⚡ Circuit Breaker Status\n');
+
+    if (!metrics || metrics.openCircuits === 0) {
+      console.log('  All circuits are CLOSED (healthy).\n');
+    } else {
+      console.log(
+        `  ⚠️  ${metrics.openCircuits} circuit(s) OPEN — tools unavailable until recovery timeout expires.\n`,
+      );
+      console.log('  Run: conductor health --json for per-tool details.\n');
+    }
+
+    console.log(`  Total tool calls: ${metrics?.totalToolCalls ?? 0}`);
+    console.log(`  Failed calls:     ${metrics?.failedToolCalls ?? 0}`);
+    console.log(`  Avg latency:      ${metrics?.avgLatencyMs ?? 0}ms`);
+    console.log('');
+    console.log('  To reset a specific circuit: conductor circuit reset <tool>\n');
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`  ❌ ${msg}\n`);
+  }
+}
+
+export async function circuitReset(conductor: Conductor, tool: string): Promise<void> {
+  await conductor.initialize();
+
+  // Circuit breaker reset requires the server process. We emit a signal file
+  // that the running server will pick up, or print guidance if no server is running.
+  console.log('');
+  console.log(`  ℹ️  Circuit breaker state lives in the running MCP server process.`);
+  console.log(`  To reset "${tool}":`);
+  console.log(`    1. Restart the MCP server:  conductor mcp start`);
+  console.log(`    2. Or wait for the recovery timeout to expire (default: 30s)`);
+  console.log('');
+}