maestro-agent 0.0.1 → 0.0.3

package/src/skills/builtin.ts

@@ -0,0 +1,155 @@
+import type { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { now } from "../core/db";
+import { syncAllSkills } from "../api/skills";
+
+const ALL_AGENT_PLATFORMS = {
+  claude: true,
+  codex: true,
+  gemini: true,
+  opencode: true,
+  hermes: true,
+};
+
+const TASK_WORKFLOW_ID = "skill_task_workflow";
+const TASK_WORKFLOW_NAME = "task-workflow";
+const TASK_WORKFLOW_DESCRIPTION =
+  "Common workflow operating method for agents: inspect task context, discover valid actions, and transition through Maestro instead of assuming fixed statuses or actions.";
+
+const TASK_WORKFLOW_MD = `# task-workflow
+
+Use this skill whenever you are working on a Maestro task.
+
+This skill teaches the workflow method. It does not define a fixed workflow. Do not assume any particular status names or action names. Each workspace or project may define its own workflow, and the valid next actions can change by task state.
+
+## Operating Loop
+
+1. Inspect the current task before acting:
+
+\`\`\`bash
+maestro inbox task show "$MAESTRO_TASK_ID" --json
+\`\`\`
+
+2. Before changing state, discover the valid workflow actions:
+
+\`\`\`bash
+maestro inbox task actions "$MAESTRO_TASK_ID" --json
+\`\`\`
+
+3. Pick the action whose meaning matches your real outcome, then transition through Maestro:
+
+\`\`\`bash
+maestro inbox task transition "$MAESTRO_TASK_ID" "<action_id>" --summary "What changed and why"
+\`\`\`
+
+4. If no valid action matches the situation, add a task note with the current evidence and escalate instead of inventing a status.
+
+## Rules
+
+- Treat the task's workflow definition as the source of truth.
+- Never update task status by writing directly to the database or by assuming a hardcoded state.
+- Never use old fixed lifecycle commands; always use actions and transition.
+- Prefer concise summaries that explain what was completed, what remains, and any review or handoff context.
+- If workflow commands are unavailable, report that limitation in the task thread and continue with the closest supported Maestro command.
+`;
+
+interface BuiltinSkillResult {
+  installed: { id: string; name: string }[];
+  updated: { id: string; name: string }[];
+  sync?: { synced: number; errors: string[] };
+}
+
+interface EnsureBuiltinSkillsOptions {
+  sync?: boolean;
+}
+
+export function ensureBuiltinSkills(
+  db: Database,
+  hubDir: string,
+  options: EnsureBuiltinSkillsOptions = {}
+): BuiltinSkillResult {
+  const result: BuiltinSkillResult = { installed: [], updated: [] };
+  const sync = options.sync ?? true;
+
+  ensureTaskWorkflowSkill(db, hubDir, result);
+
+  if (sync) {
+    result.sync = syncAllSkills(db, hubDir);
+  }
+
+  return result;
+}
+
+function ensureTaskWorkflowSkill(db: Database, hubDir: string, result: BuiltinSkillResult): void {
+  const skillsDir = join(hubDir, "skills");
+  mkdirSync(skillsDir, { recursive: true });
+
+  const existing = db
+    .query("SELECT * FROM skill WHERE id = ? OR name = ?")
+    .get(TASK_WORKFLOW_ID, TASK_WORKFLOW_NAME) as any | null;
+  const id = existing?.id || TASK_WORKFLOW_ID;
+  const skillDir = join(skillsDir, id);
+  const skillPath = join(skillDir, "SKILL.md");
+  const ts = now();
+
+  mkdirSync(skillDir, { recursive: true });
+
+  const currentContent = existsSync(skillPath) ? readFileSync(skillPath, "utf-8") : "";
+  const contentChanged = currentContent !== TASK_WORKFLOW_MD;
+  if (contentChanged) {
+    writeFileSync(skillPath, TASK_WORKFLOW_MD, "utf-8");
+  }
+
+  if (!existing) {
+    db.run(
+      `INSERT INTO skill (id, name, description, source, source_url, platforms_json, enabled, config_json, installed_at, updated_at)
+       VALUES (?, ?, ?, 'local', NULL, ?, 1, ?, ?, ?)`,
+      [
+        id,
+        TASK_WORKFLOW_NAME,
+        TASK_WORKFLOW_DESCRIPTION,
+        JSON.stringify(ALL_AGENT_PLATFORMS),
+        JSON.stringify({ builtin: true }),
+        ts,
+        ts,
+      ]
+    );
+    result.installed.push({ id, name: TASK_WORKFLOW_NAME });
+    return;
+  }
+
+  const expectedPlatformsJson = JSON.stringify(ALL_AGENT_PLATFORMS);
+  const expectedConfigJson = JSON.stringify({ builtin: true });
+  const needsDbUpdate =
+    existing.name !== TASK_WORKFLOW_NAME ||
+    existing.description !== TASK_WORKFLOW_DESCRIPTION ||
+    existing.source !== "local" ||
+    existing.platforms_json !== expectedPlatformsJson ||
+    existing.enabled !== 1 ||
+    existing.config_json !== expectedConfigJson ||
+    contentChanged;
+
+  if (needsDbUpdate) {
+    db.run(
+      `UPDATE skill
+       SET name = ?,
+           description = ?,
+           source = 'local',
+           platforms_json = ?,
+           enabled = 1,
+           config_json = ?,
+           updated_at = ?
+       WHERE id = ?`,
+      [
+        TASK_WORKFLOW_NAME,
+        TASK_WORKFLOW_DESCRIPTION,
+        expectedPlatformsJson,
+        expectedConfigJson,
+        ts,
+        id,
+      ]
+    );
+    result.updated.push({ id, name: TASK_WORKFLOW_NAME });
+  }
+}

package/src/skills/skill-extractor.ts

@@ -0,0 +1,452 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { getSkillsDir } from "../api/skills";
+import { generateId, now } from "../core/db";
+import type { HubContext } from "../core/server";
+import type { SkillFrontmatter } from "./skill-md";
+import { serializeSkillMd } from "./skill-md";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface SkillExtractionResult {
+  extracted: boolean;
+  skill_id?: string;
+  skill_name?: string;
+  reason?: string;
+}
+
+export interface SkillExtractionConfig {
+  enabled: boolean;
+  min_transcript_length: number;   // Minimum transcript length to consider
+  max_transcript_length: number;   // Truncate beyond this
+  auto_enable: boolean;            // Auto-enable extracted skills
+  require_approval: boolean;       // Mark as draft, require human approval
+}
+
+const DEFAULT_CONFIG: SkillExtractionConfig = {
+  enabled: true,
+  min_transcript_length: 500,
+  max_transcript_length: 50_000,
+  auto_enable: false,
+  require_approval: true,
+};
+
+// ─── Core Extraction ─────────────────────────────────────────────────────────
+
+/**
+ * Analyze a session transcript and extract a reusable skill if a clear
+ * repeatable pattern is detected.
+ *
+ * Uses heuristic analysis (no LLM dependency) to identify:
+ * - Multi-step procedures that could be automated
+ * - File manipulation patterns
+ * - Command sequences
+ * - Code generation templates
+ */
+export function extractSkillFromTranscript(
+  ctx: HubContext,
+  sessionId: string,
+  config: Partial<SkillExtractionConfig> = {}
+): SkillExtractionResult {
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+  if (!cfg.enabled) return { extracted: false, reason: "extraction_disabled" };
+
+  // Load session and transcript
+  const session = ctx.db.query("SELECT * FROM session WHERE id = ?").get(sessionId) as any;
+  if (!session) return { extracted: false, reason: "session_not_found" };
+  if (!session.transcript_path || !existsSync(session.transcript_path)) {
+    return { extracted: false, reason: "no_transcript" };
+  }
+
+  const transcript = readFileSync(session.transcript_path, "utf-8");
+  if (transcript.length < cfg.min_transcript_length) {
+    return { extracted: false, reason: "transcript_too_short" };
+  }
+
+  // Get task context for naming
+  const task = session.task_id
+    ? ctx.db.query("SELECT title, project_id FROM task WHERE id = ?").get(session.task_id) as any
+    : null;
+
+  // Analyze transcript for extractable patterns
+  const analysis = analyzeTranscript(transcript.slice(0, cfg.max_transcript_length));
+  if (!analysis.extractable) {
+    return { extracted: false, reason: analysis.reason };
+  }
+
+  // Check for duplicate skill
+  const existingSkill = ctx.db.query(
+    "SELECT id FROM skill WHERE name = ?"
+  ).get(analysis.skillName) as any;
+  if (existingSkill) {
+    return { extracted: false, reason: "duplicate_skill", skill_id: existingSkill.id };
+  }
+
+  // Generate SKILL.md content
+  const frontmatter: SkillFrontmatter = {
+    name: analysis.skillName,
+    description: analysis.description,
+    version: "1.0.0",
+    metadata: {
+      author: "auto-extractor",
+      source_session: sessionId,
+      source_task: session.task_id || null,
+      tags: analysis.tags,
+      extracted_at: new Date().toISOString(),
+    },
+    platforms: { claude: true, codex: true, gemini: true, opencode: true },
+  };
+
+  const body = buildSkillBody(analysis);
+  const skillContent = serializeSkillMd(frontmatter, body);
+
+  // Write skill to filesystem
+  const skillsDir = getSkillsDir(ctx.hubDir);
+  const skillDir = join(skillsDir, analysis.skillName);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(join(skillDir, "SKILL.md"), skillContent);
+
+  // Insert into DB
+  const skillId = generateId("skill");
+  const ts = now();
+  ctx.db.run(
+    `INSERT INTO skill (id, name, description, source, platforms_json, enabled, config_json, installed_at, updated_at)
+     VALUES (?, ?, ?, 'local', ?, ?, ?, ?, ?)`,
+    [
+      skillId,
+      analysis.skillName,
+      analysis.description,
+      JSON.stringify({ claude: true, codex: true, gemini: true, opencode: true }),
+      cfg.auto_enable && !cfg.require_approval ? 1 : 0,
+      JSON.stringify({ auto_extracted: true, source_session: sessionId }),
+      ts,
+      ts,
+    ]
+  );
+
+  ctx.bus.publish("skill.extracted", {
+    skill_id: skillId,
+    skill_name: analysis.skillName,
+    session_id: sessionId,
+    task_id: session.task_id,
+  });
+
+  return { extracted: true, skill_id: skillId, skill_name: analysis.skillName };
+}
+
+// ─── Transcript Analysis ─────────────────────────────────────────────────────
+
+interface TranscriptAnalysis {
+  extractable: boolean;
+  reason?: string;
+  skillName: string;
+  description: string;
+  tags: string[];
+  steps: string[];
+  commands: string[];
+  filePatterns: string[];
+  codeTemplates: string[];
+}
+
+function analyzeTranscript(transcript: string): TranscriptAnalysis {
+  // Skip transcripts that are primarily maestro agent-hub communication
+  const maestroMentions = (transcript.match(/maestro\s+(chat|inbox|task|session|heartbeat|agent|poll)/gi) || []).length;
+  const totalLines = transcript.split("\n").length;
+  if (maestroMentions > 3 && maestroMentions / totalLines > 0.1) {
+    return {
+      extractable: false,
+      reason: "infrastructure_only",
+      skillName: "",
+      description: "",
+      tags: [],
+      steps: [],
+      commands: [],
+      filePatterns: [],
+      codeTemplates: [],
+    };
+  }
+
+  const commands = extractCommands(transcript);
+  const filePatterns = extractFilePatterns(transcript);
+  const steps = extractProcedureSteps(transcript);
+  const codeTemplates = extractCodeTemplates(transcript);
+
+  // Determine if there's a repeatable pattern worth extracting
+  const hasSubstantialSteps = steps.length >= 3;
+  const hasCommands = commands.length >= 2;
+  const hasFileOps = filePatterns.length >= 2;
+  const hasCodeGen = codeTemplates.length >= 1;
+
+  const extractable = hasSubstantialSteps || (hasCommands && hasFileOps) || hasCodeGen;
+
+  if (!extractable) {
+    return {
+      extractable: false,
+      reason: "no_repeatable_pattern",
+      skillName: "",
+      description: "",
+      tags: [],
+      steps: [],
+      commands: [],
+      filePatterns: [],
+      codeTemplates: [],
+    };
+  }
+
+  // Generate skill name from patterns
+  const skillName = inferSkillName(steps, commands, filePatterns);
+  const description = inferDescription(steps, commands, filePatterns);
+  const tags = inferTags(commands, filePatterns, codeTemplates);
+
+  return {
+    extractable: true,
+    skillName,
+    description,
+    tags,
+    steps,
+    commands,
+    filePatterns,
+    codeTemplates,
+  };
+}
+
+// ─── Pattern Extraction ──────────────────────────────────────────────────────
+
+// Maestro infrastructure commands that should never be extracted as skills
+const INFRA_COMMAND_PATTERNS = [
+  /^maestro\s/,
+  /^hub\s/,
+  /maestro\s+chat\s+poll/,
+  /maestro\s+inbox/,
+  /maestro\s+task\s+transition/,
+  /maestro\s+session/,
+  /maestro\s+heartbeat/,
+  /maestro\s+start/,
+  /maestro\s+stop/,
+  /maestro\s+agent/,
+];
+
+function isInfraCommand(cmd: string): boolean {
+  const lower = cmd.toLowerCase();
+  return INFRA_COMMAND_PATTERNS.some((p) => p.test(lower));
+}
+
+function extractCommands(transcript: string): string[] {
+  const commands: string[] = [];
+  const patterns = [
+    /(?:RunCommand|run_command|Execute)\s*\(\s*(?:command\s*[:=]\s*)?["']([^"']+)["']/g,
+    /\$\s+(.+)/gm,
+    /```(?:bash|sh|shell|zsh)\n([\s\S]*?)```/g,
+  ];
+
+  for (const pattern of patterns) {
+    for (const m of transcript.matchAll(pattern)) {
+      const cmd = m[1].trim();
+      if (cmd && cmd.length < 200 && !cmd.toLowerCase().includes("password") && !cmd.toLowerCase().includes("token") && !isInfraCommand(cmd)) {
+        commands.push(cmd);
+      }
+    }
+  }
+
+  return [...new Set(commands)].slice(0, 20);
+}
+
+function extractFilePatterns(transcript: string): string[] {
+  const files = new Set<string>();
+  const patterns = [
+    /(?:Write|Edit|Read)\s*\(\s*(?:file_path\s*[:=]\s*)?["']([^"']+)["']/g,
+    /(?:created?|modified?|updated?|wrote)\s+(?:file\s+)?[`"]([^`"]+)[`"]/gi,
+  ];
+
+  for (const pattern of patterns) {
+    for (const m of transcript.matchAll(pattern)) {
+      if (m[1]) files.add(m[1]);
+    }
+  }
+
+  return [...files].slice(0, 20);
+}
+
+function extractProcedureSteps(transcript: string): string[] {
+  const steps: string[] = [];
+
+  // Look for numbered steps
+  const numberedPattern = /(?:^|\n)\s*(\d+[.)]\s+.+)/g;
+  for (const m of transcript.matchAll(numberedPattern)) {
+    steps.push(m[1].trim());
+  }
+
+  // Look for bullet-point procedures
+  const bulletPattern = /(?:^|\n)\s*[-*]\s+((?:First|Then|Next|Finally|After|Before|Now|Create|Add|Update|Install|Configure|Set up|Run|Execute|Build|Deploy).+)/gi;
+  for (const m of transcript.matchAll(bulletPattern)) {
+    steps.push(m[1].trim());
+  }
+
+  // Look for action descriptions in context
+  const actionPattern = /(?:I'll|Let me|Going to|We need to|I will)\s+(.+?)(?:\.|$)/gm;
+  for (const m of transcript.matchAll(actionPattern)) {
+    const step = m[1].trim();
+    if (step.length > 10 && step.length < 200) {
+      steps.push(step);
+    }
+  }
+
+  return [...new Set(steps)].slice(0, 15);
+}
+
+function extractCodeTemplates(transcript: string): string[] {
+  const templates: string[] = [];
+  const codeBlockPattern = /```(\w+)?\n([\s\S]*?)```/g;
+
+  for (const m of transcript.matchAll(codeBlockPattern)) {
+    const lang = m[1];
+    const code = m[2].trim();
+    // Only extract substantial code blocks that look like templates
+    if (code.length > 50 && code.length < 5000 && lang) {
+      templates.push(`\`\`\`${lang}\n${code}\n\`\`\``);
+    }
+  }
+
+  return templates.slice(0, 5);
+}
+
+// ─── Inference ───────────────────────────────────────────────────────────────
+
+function inferSkillName(steps: string[], commands: string[], files: string[]): string {
+  // Try to infer from common patterns
+  const allText = [...steps, ...commands].join(" ").toLowerCase();
+
+  // Check for common task patterns
+  const patterns: [RegExp, string][] = [
+    [/docker|container|compose/, "docker-setup"],
+    [/test|spec|jest|vitest|bun test/, "run-tests"],
+    [/lint|eslint|prettier|format/, "lint-and-format"],
+    [/deploy|publish|release/, "deploy"],
+    [/build|compile|bundle/, "build-project"],
+    [/migrate|migration|schema/, "db-migration"],
+    [/refactor/, "refactor"],
+    [/review|cr\b/, "code-review"],
+    [/setup|init|scaffold|create.*project/, "project-setup"],
+    [/api|endpoint|route/, "api-endpoint"],
+    [/component|widget|ui/, "ui-component"],
+    [/auth|login|jwt|oauth/, "auth-setup"],
+  ];
+
+  for (const [regex, name] of patterns) {
+    if (regex.test(allText)) {
+      // Make unique with a short hash from content
+      const hash = simpleHash(allText).slice(0, 4);
+      return `${name}-${hash}`;
+    }
+  }
+
+  // Fallback: generate from first meaningful step
+  if (steps.length > 0) {
+    const slug = steps[0]
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "")
+      .slice(0, 30);
+    return slug || `extracted-skill-${simpleHash(allText).slice(0, 6)}`;
+  }
+
+  return `extracted-skill-${simpleHash(allText).slice(0, 6)}`;
+}
+
+function inferDescription(steps: string[], commands: string[], files: string[]): string {
+  if (steps.length > 0) {
+    // Use first 2-3 steps as description
+    const desc = steps.slice(0, 3).join("; ");
+    return desc.length > 200 ? desc.slice(0, 197) + "..." : desc;
+  }
+
+  if (commands.length > 0) {
+    return `Automates: ${commands.slice(0, 3).join(", ")}`;
+  }
+
+  return `Extracted procedure operating on ${files.length} files`;
+}
+
+function inferTags(commands: string[], files: string[], codeTemplates: string[]): string[] {
+  const tags = new Set<string>();
+
+  // Infer from file extensions
+  for (const f of files) {
+    if (f.endsWith(".ts") || f.endsWith(".tsx")) tags.add("typescript");
+    if (f.endsWith(".js") || f.endsWith(".jsx")) tags.add("javascript");
+    if (f.endsWith(".py")) tags.add("python");
+    if (f.endsWith(".go")) tags.add("go");
+    if (f.endsWith(".rs")) tags.add("rust");
+    if (f.endsWith(".sql")) tags.add("sql");
+    if (f.endsWith(".css") || f.endsWith(".scss")) tags.add("styling");
+    if (f.includes("test") || f.includes("spec")) tags.add("testing");
+  }
+
+  // Infer from commands
+  const cmdStr = commands.join(" ").toLowerCase();
+  if (cmdStr.includes("npm") || cmdStr.includes("bun") || cmdStr.includes("yarn")) tags.add("nodejs");
+  if (cmdStr.includes("git")) tags.add("git");
+  if (cmdStr.includes("docker")) tags.add("docker");
+
+  return [...tags].slice(0, 8);
+}
+
+// ─── Skill Body Builder ──────────────────────────────────────────────────────
+
+function buildSkillBody(analysis: TranscriptAnalysis): string {
+  const sections: string[] = [];
+
+  sections.push(`# ${analysis.skillName}\n`);
+  sections.push(`${analysis.description}\n`);
+
+  if (analysis.steps.length > 0) {
+    sections.push("## Procedure\n");
+    for (let i = 0; i < analysis.steps.length; i++) {
+      sections.push(`${i + 1}. ${analysis.steps[i]}`);
+    }
+    sections.push("");
+  }
+
+  if (analysis.commands.length > 0) {
+    sections.push("## Commands\n");
+    sections.push("```bash");
+    for (const cmd of analysis.commands.slice(0, 10)) {
+      sections.push(cmd);
+    }
+    sections.push("```\n");
+  }
+
+  if (analysis.filePatterns.length > 0) {
+    sections.push("## Files Involved\n");
+    for (const f of analysis.filePatterns) {
+      sections.push(`- \`${f}\``);
+    }
+    sections.push("");
+  }
+
+  if (analysis.codeTemplates.length > 0) {
+    sections.push("## Code Templates\n");
+    for (const tpl of analysis.codeTemplates.slice(0, 3)) {
+      sections.push(tpl);
+      sections.push("");
+    }
+  }
+
+  return sections.join("\n");
+}
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+function simpleHash(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return Math.abs(hash).toString(36);
+}
+
+// ─── Exported for testing ────────────────────────────────────────────────────
+export { analyzeTranscript, extractCodeTemplates, extractCommands, extractFilePatterns, extractProcedureSteps };
+