maestro-agent 0.0.1 → 0.0.2

package/src/roles/index.ts

@@ -0,0 +1,258 @@
+import type { Database } from "bun:sqlite";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join, dirname } from "path";
+import { now } from "../core/db";
+
+export interface LoadedRole {
+  id: string;
+  name: string;
+  version: string;
+  role_md_path: string;
+  workspace_id?: string | null;
+  project_id?: string | null;
+  capabilities: string[];
+  preferred_runtimes: string[];
+  headcount: number;
+  extends?: string;
+}
+
+export interface RoleReloadState {
+  signature: string;
+}
+
+export function reloadRolesIfChanged(db: Database, rolesDir: string, state: RoleReloadState) {
+  const signature = roleDirectorySignature(rolesDir);
+  if (signature === state.signature) {
+    return { changed: false, roles: [] as LoadedRole[] };
+  }
+  state.signature = signature;
+  return { changed: true, roles: syncRolesFromDirectory(db, rolesDir) };
+}
+
+export function syncRolesFromDirectory(db: Database, rolesDir: string): LoadedRole[] {
+  if (!existsSync(rolesDir)) return [];
+  const roles: LoadedRole[] = [];
+
+  const topFiles = collectRoleMarkdownFiles(rolesDir, { includeBase: false });
+
+  for (const filePath of topFiles) {
+    const role = loadRoleFile(filePath, rolesDir);
+    roles.push(role);
+    upsertRole(db, role);
+    reloadIdleAgents(db, role);
+  }
+
+  return roles;
+}
+
+function collectRoleMarkdownFiles(rolesDir: string, opts: { includeBase: boolean }): string[] {
+  const files: string[] = [];
+  const scan = (dir: string) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!opts.includeBase && entry.name === "base") continue;
+        scan(path);
+        continue;
+      }
+      if (entry.isFile() && entry.name.endsWith(".md")) files.push(path);
+    }
+  };
+
+  scan(rolesDir);
+  return files;
+}
+
+export function roleDirectorySignature(rolesDir: string): string {
+  if (!existsSync(rolesDir)) return "";
+  const files = collectRoleMarkdownFiles(rolesDir, { includeBase: true });
+
+  return files
+    .sort()
+    .map((path) => {
+      const stat = statSync(path);
+      return `${path}:${stat.mtimeMs}:${stat.size}`;
+    })
+    .join("|");
+}
+
+export function loadRoleFile(path: string, rolesDir?: string): LoadedRole {
+  const content = readFileSync(path, "utf-8");
+  const frontmatter = parseFrontmatter(content);
+  const id = String(frontmatter.id || filenameId(path));
+  return {
+    id,
+    name: String(frontmatter.name || id),
+    version: String(frontmatter.version || String(statSync(path).mtimeMs)),
+    role_md_path: path,
+    workspace_id: frontmatter.workspace_id || null,
+    project_id: frontmatter.project_id || null,
+    capabilities: parseList(frontmatter.capabilities),
+    preferred_runtimes: parseList(frontmatter.preferred_runtimes),
+    headcount: Number(frontmatter.default_headcount || frontmatter.headcount || 1),
+    extends: frontmatter.extends || undefined,
+  };
+}
+
+/**
+ * Build the full role prompt by resolving the extends inheritance chain.
+ * Returns the merged content (base first, role last) with frontmatter stripped.
+ * Automatically appends inbox-cheatsheet.md and safety.md from base/.
+ */
+export function buildFullRolePrompt(rolesDir: string, roleMdPath: string): string {
+  const parts: string[] = [];
+
+  // Resolve inheritance chain (base → ... → role)
+  const chain = resolveInheritanceChain(rolesDir, roleMdPath);
+
+  // Collect content in order (ancestors first, role last)
+  for (const filePath of chain) {
+    const content = readFileSync(filePath, "utf-8");
+    parts.push(stripFrontmatter(content));
+  }
+
+  // Append inbox-cheatsheet and safety (if not already in chain)
+  const baseDir = join(rolesDir, "base");
+  const cheatsheetPath = join(baseDir, "inbox-cheatsheet.md");
+  const safetyPath = join(baseDir, "safety.md");
+
+  if (existsSync(cheatsheetPath) && !chain.includes(cheatsheetPath)) {
+    parts.push(readFileSync(cheatsheetPath, "utf-8"));
+  }
+  if (existsSync(safetyPath) && !chain.includes(safetyPath)) {
+    parts.push(readFileSync(safetyPath, "utf-8"));
+  }
+
+  return parts.join("\n\n---\n\n");
+}
+
+/**
+ * Resolve the inheritance chain for a role file.
+ * Returns an array of file paths from root ancestor to the role itself.
+ */
+function resolveInheritanceChain(rolesDir: string, roleMdPath: string): string[] {
+  const chain: string[] = [];
+  const visited = new Set<string>();
+  let current: string | null = roleMdPath;
+  const maxDepth = 5;
+
+  // Walk up the extends chain
+  const stack: string[] = [];
+  while (current && stack.length < maxDepth) {
+    const resolved = resolveRolePath(rolesDir, current);
+    if (!resolved || !existsSync(resolved) || visited.has(resolved)) break;
+    visited.add(resolved);
+    stack.push(resolved);
+
+    const content = readFileSync(resolved, "utf-8");
+    const fm = parseFrontmatter(content);
+    current = fm.extends || null;
+  }
+
+  // Reverse so ancestors come first
+  stack.reverse();
+  chain.push(...stack);
+  return chain;
+}
+
+/**
+ * Resolve a role path reference (could be relative like "base/agent.md" or absolute)
+ */
+function resolveRolePath(rolesDir: string, ref: string): string | null {
+  // If it's already an absolute path, use it
+  if (ref.startsWith("/") && existsSync(ref)) return ref;
+  // Resolve relative to rolesDir
+  const resolved = join(rolesDir, ref);
+  if (existsSync(resolved)) return resolved;
+  // Try as-is
+  if (existsSync(ref)) return ref;
+  return null;
+}
+
+function upsertRole(db: Database, role: LoadedRole) {
+  const ts = now();
+  db.run(
+    `INSERT INTO role (id, workspace_id, project_id, name, role_md_path, version, capabilities_json, preferred_runtimes_json, headcount, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       workspace_id = excluded.workspace_id,
+       project_id = excluded.project_id,
+       name = excluded.name,
+       role_md_path = excluded.role_md_path,
+       version = excluded.version,
+       capabilities_json = excluded.capabilities_json,
+       preferred_runtimes_json = excluded.preferred_runtimes_json,
+       headcount = excluded.headcount,
+       updated_at = excluded.updated_at`,
+    [
+      role.id,
+      role.workspace_id || null,
+      role.project_id || null,
+      role.name,
+      role.role_md_path,
+      role.version,
+      JSON.stringify(role.capabilities),
+      JSON.stringify(role.preferred_runtimes),
+      role.headcount,
+      ts,
+      ts,
+    ]
+  );
+}
+
+function reloadIdleAgents(db: Database, role: LoadedRole) {
+  const rows = db.query("SELECT id, metrics_json FROM agent WHERE role_id = ? AND status = 'idle'").all(role.id) as any[];
+  const ts = now();
+  for (const agent of rows) {
+    const metrics = JSON.parse(agent.metrics_json || "{}");
+    metrics.role_version = role.version;
+    metrics.role_reloaded_at = ts;
+    db.run("UPDATE agent SET metrics_json = ?, last_active_at = ? WHERE id = ?", [
+      JSON.stringify(metrics),
+      ts,
+      agent.id,
+    ]);
+  }
+}
+
+export function parseFrontmatter(content: string): Record<string, string> {
+  if (!content.startsWith("---")) return {};
+  const end = content.indexOf("\n---", 3);
+  if (end === -1) return {};
+  const block = content.slice(3, end).trim();
+  const values: Record<string, string> = {};
+  for (const line of block.split("\n")) {
+    const index = line.indexOf(":");
+    if (index === -1) continue;
+    const key = line.slice(0, index).trim();
+    const value = line.slice(index + 1).trim();
+    values[key] = value;
+  }
+  return values;
+}
+
+export function stripFrontmatter(content: string): string {
+  if (!content.startsWith("---")) return content;
+  const end = content.indexOf("\n---", 3);
+  if (end === -1) return content;
+  return content.slice(end + 4).trim();
+}
+
+function parseList(value: unknown): string[] {
+  if (!value) return [];
+  const text = String(value).trim();
+  if (!text) return [];
+  if (text.startsWith("[") && text.endsWith("]")) {
+    return text
+      .slice(1, -1)
+      .split(",")
+      .map((item) => item.trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean);
+  }
+  return text.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+function filenameId(path: string): string {
+  return path.split("/").pop()!.replace(/\.md$/, "");
+}

package/src/roles/prompt-assembler.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import type { HubContext } from "../core/server";
+import { buildFullRolePrompt } from "./index";
+
+/**
+ * Assemble the four-layer prompt for an agent session:
+ *   1. [system] Hub runtime (base/agent.md + cheatsheet + safety — via buildFullRolePrompt inheritance)
+ *   2. [role]   Role-specific content (resolved via extends chain)
+ *   3. [project] Project charter (if available)
+ *   4. [task]   Task description + done_when criteria
+ */
+export function assemblePrompt(ctx: HubContext, opts: {
+  agentId: string;
+  taskId?: string | null;
+}): string {
+  const sections: string[] = [];
+  const rolesDir = join(ctx.hubDir, "roles");
+
+  // Resolve agent → role → role_md_path
+  const agent = ctx.db.query("SELECT * FROM agent WHERE id = ?").get(opts.agentId) as any;
+  if (!agent?.role_id) {
+    // No role assigned, return minimal prompt
+    sections.push("# MAESTRO Agent\n\nYou are an AI Agent in the MAESTRO system. No specific role has been assigned.");
+  } else {
+    const role = ctx.db.query("SELECT * FROM role WHERE id = ?").get(agent.role_id) as any;
+
+    // Layer 1+2: Role prompt (includes base via extends chain)
+    if (role?.role_md_path && existsSync(role.role_md_path)) {
+      const rolePrompt = buildFullRolePrompt(rolesDir, role.role_md_path);
+      sections.push(rolePrompt);
+    } else {
+      sections.push(`# Role: ${role?.name || agent.role_id}\n\nRole definition file not found.`);
+    }
+
+    // Layer 3: Project charter
+    if (role?.project_id) {
+      const project = ctx.db.query("SELECT * FROM project WHERE id = ?").get(role.project_id) as any;
+      if (project?.charter_template) {
+        sections.push(`# Project Charter: ${project.name}\n\n${project.charter_template}`);
+      }
+    } else if (role?.workspace_id) {
+      // Try to find project through workspace
+      const project = ctx.db.query(
+        "SELECT * FROM project WHERE workspace_id = ? ORDER BY created_at DESC LIMIT 1"
+      ).get(role.workspace_id) as any;
+      if (project?.charter_template) {
+        sections.push(`# Project Charter: ${project.name}\n\n${project.charter_template}`);
+      }
+    }
+  }
+
+  // Layer 4: Task context
+  if (opts.taskId) {
+    const task = ctx.db.query("SELECT * FROM task WHERE id = ?").get(opts.taskId) as any;
+    if (task) {
+      let taskSection = `# Current Task\n\n**ID:** ${task.id}\n**Title:** ${task.title}\n`;
+      if (task.description) taskSection += `**Description:** ${task.description}\n`;
+      if (task.done_when_json) {
+        try {
+          const doneWhen = JSON.parse(task.done_when_json);
+          taskSection += `**Done When:** ${JSON.stringify(doneWhen)}\n`;
+        } catch {}
+      }
+      if (task.required_capabilities_json) {
+        taskSection += `**Required Capabilities:** ${task.required_capabilities_json}\n`;
+      }
+
+      // Include recent thread items
+      const threadItems = ctx.db.query(
+        "SELECT * FROM task_thread_item WHERE task_id = ? ORDER BY created_at DESC LIMIT 5"
+      ).all(opts.taskId) as any[];
+      if (threadItems.length > 0) {
+        taskSection += `\n## Recent Thread\n`;
+        for (const item of threadItems.reverse()) {
+          taskSection += `- [${item.author}] ${item.content}\n`;
+        }
+      }
+
+      sections.push(taskSection);
+    }
+  }
+
+  return sections.join("\n\n---\n\n");
+}

package/src/roles/workspace-role.ts

@@ -0,0 +1,155 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import type { Database } from "bun:sqlite";
+import { generateId, now } from "../core/db";
+
+export interface WorkspaceRoleSpec {
+  workspaceId: string;
+  projectId?: string | null;
+  id?: string;
+  name: string;
+  capabilities?: string[];
+  preferredRuntimes?: string[];
+  headcount?: number;
+  runtimeId?: string | null;
+  hubDir?: string;
+}
+
+export interface WorkspaceRoleResult {
+  role: any;
+  agents: any[];
+  roleMdPath: string;
+  roleMdContent: string;
+}
+
+type PublishFn = (type: string, payload: any) => void;
+
+export function workspaceRoleMdPath(hubDir: string | undefined, workspaceId: string, roleId: string): string {
+  return hubDir
+    ? join(hubDir, "roles", workspaceId, `${roleId}.md`)
+    : join("/roles", workspaceId, `${roleId}.md`);
+}
+
+export function renderWorkspaceRoleMarkdown(spec: WorkspaceRoleSpec & { roleId: string }): string {
+  const capabilities = JSON.stringify(spec.capabilities || []);
+  const preferredRuntimes = JSON.stringify(spec.preferredRuntimes || []);
+  const headcount = Math.max(1, Number(spec.headcount || 1));
+
+  return `---
+id: ${spec.roleId}
+name: ${spec.name}
+workspace_id: ${spec.workspaceId}
+${spec.projectId ? `project_id: ${spec.projectId}` : ""}
+capabilities: ${capabilities}
+preferred_runtimes: ${preferredRuntimes}
+headcount: ${headcount}
+extends: base/agent.md
+---
+
+# ${spec.name}
+
+This role was created from the workspace role manager.
+`;
+}
+
+export function createWorkspaceRole(
+  db: Database,
+  spec: WorkspaceRoleSpec,
+  publish?: PublishFn,
+): WorkspaceRoleResult {
+  const name = String(spec.name || "").trim();
+  if (!name) throw new Error("Role name is required");
+  if (!spec.workspaceId) throw new Error("workspaceId is required");
+
+  const roleId = buildWorkspaceRoleId(spec.workspaceId, spec.id || name);
+  const ts = now();
+  const roleMdPath = workspaceRoleMdPath(spec.hubDir, spec.workspaceId, roleId);
+  const roleMdContent = renderWorkspaceRoleMarkdown({ ...spec, roleId, name });
+
+  if (spec.hubDir) {
+    const roleDir = join(spec.hubDir, "roles", spec.workspaceId);
+    mkdirSync(roleDir, { recursive: true });
+    writeFileSync(roleMdPath, roleMdContent, "utf-8");
+  }
+
+  db.run(
+    `INSERT INTO role (id, workspace_id, project_id, name, role_md_path, capabilities_json, preferred_runtimes_json, headcount, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       workspace_id = excluded.workspace_id,
+       project_id = excluded.project_id,
+       name = excluded.name,
+       role_md_path = excluded.role_md_path,
+       capabilities_json = excluded.capabilities_json,
+       preferred_runtimes_json = excluded.preferred_runtimes_json,
+       headcount = excluded.headcount,
+       updated_at = excluded.updated_at`,
+    [
+      roleId,
+      spec.workspaceId,
+      spec.projectId || null,
+      name,
+      roleMdPath,
+      JSON.stringify(Array.isArray(spec.capabilities) ? spec.capabilities : []),
+      JSON.stringify(Array.isArray(spec.preferredRuntimes) ? spec.preferredRuntimes : []),
+      Math.max(1, Number(spec.headcount || 1)),
+      ts,
+      ts,
+    ],
+  );
+
+  const role = db.query("SELECT * FROM role WHERE id = ?").get(roleId) as any;
+  const safePublish = publish || (() => {});
+  const agents = spawnRoleAgents(db, role, {
+    runtimeId: spec.runtimeId || null,
+    count: Math.max(1, Number(spec.headcount || 1)),
+    hubDir: spec.hubDir,
+    publish: safePublish,
+  });
+
+  safePublish("role.created", { id: roleId, workspace_id: spec.workspaceId, name });
+  return { role, agents, roleMdPath, roleMdContent };
+}
+
+export function buildWorkspaceRoleId(workspaceId: string, rawId: string): string {
+  const baseId = String(rawId || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  const scopedBaseId = baseId || generateId("role");
+  const scopedId = `${workspaceId}_${scopedBaseId}`;
+  return scopedId.replace(/[^a-z0-9_]+/g, "_");
+}
+
+export function spawnRoleAgents(
+  db: Database,
+  role: any,
+  opts: { runtimeId?: string | null; count?: number; hubDir?: string; publish?: PublishFn },
+): any[] {
+  const count = Math.max(1, Number(opts.count || role?.headcount || 1));
+  let runtimeId = opts.runtimeId || null;
+  let runtime = runtimeId ? (db.query("SELECT * FROM agent_runtime WHERE id = ?").get(runtimeId) as any) : null;
+  if (!runtime) {
+    runtime = db.query("SELECT * FROM agent_runtime WHERE status = 'online' ORDER BY created_at DESC LIMIT 1").get() as any;
+    runtimeId = runtime?.id || runtimeId;
+  }
+  if (!runtimeId || !runtime) return [];
+
+  if (!runtime) throw new Error(`Agent runtime not found: ${runtimeId}`);
+
+  const agents: any[] = [];
+  const ts = now();
+  for (let i = 0; i < count; i++) {
+    const agentId = generateId("agent");
+    const agentName = `${role.name}-${i + 1}`;
+    const workdir = null;
+    db.run(
+      "INSERT INTO agent (id, role_id, runtime_id, name, workdir, status, metrics_json, created_at, last_active_at) VALUES (?, ?, ?, ?, ?, 'idle', '{}', ?, ?)",
+      [agentId, role.id, runtimeId, agentName, workdir, ts, ts],
+    );
+    const agent = { id: agentId, name: agentName, role_id: role.id, runtime_id: runtimeId, status: "idle", workdir };
+    agents.push(agent);
+    opts.publish?.("agent.spawned", { id: agentId, name: agentName, runtime_id: runtimeId, role_id: role.id });
+  }
+  return agents;
+}