brainiverse 0.0.0-stage → 0.1.0

package/skill/brainiverse/runtime/data/terminology.json

@@ -0,0 +1,18 @@
+{
+  "themed": {
+    "team": "Squad",
+    "project": "Mission",
+    "meeting": "War Room",
+    "invite": "Call in a specialist",
+    "task": "Mission assignment",
+    "final_review": "Mission debrief"
+  },
+  "professional": {
+    "team": "Team",
+    "project": "Project",
+    "meeting": "Meeting",
+    "invite": "Invite an agent",
+    "task": "Task",
+    "final_review": "Final review"
+  }
+}

package/skill/brainiverse/runtime/data/themes.json

@@ -0,0 +1,50 @@
+{
+  "heroes": {
+    "description": "Default: original superhero-style crew names, safe to share publicly.",
+    "terminology": "themed",
+    "identities": {
+      "leader": {"name": "Captain", "personality": "Confident, strategic, decisive", "avatar": "🛡️"},
+      "researcher": {"name": "Lumen", "personality": "Curious, insightful, investigative", "avatar": "🔭"},
+      "creative_thinker": {"name": "Spark", "personality": "Inventive, witty, unconventional", "avatar": "⚡"},
+      "analyst": {"name": "Quant", "personality": "Thoughtful, analytical, evidence-driven", "avatar": "📊"},
+      "executor": {"name": "Forge", "personality": "Practical, resourceful, action-oriented", "avatar": "🔨"},
+      "challenger": {"name": "Riddle", "personality": "Questioning, unpredictable, skeptical", "avatar": "🃏"},
+      "specialist": {"name": "Sage", "personality": "Knowledgeable, precise, exploratory", "avatar": "🧭"},
+      "communicator": {"name": "Echo", "personality": "Diplomatic, trustworthy, persuasive", "avatar": "📣"},
+      "organizer": {"name": "Atlas", "personality": "Organized, discreet, coordinated", "avatar": "🗂️"},
+      "quality_reviewer": {"name": "Sentinel", "personality": "Observant, precise, detail-oriented", "avatar": "🎯"}
+    }
+  },
+  "classic": {
+    "description": "The nicknames from the original spec. They echo comic-book characters, so keep this theme for personal use and don't ship it in anything public.",
+    "terminology": "themed",
+    "identities": {
+      "leader": {"name": "Captain", "personality": "Confident, strategic, decisive"},
+      "researcher": {"name": "Vision", "personality": "Curious, insightful, investigative"},
+      "creative_thinker": {"name": "Stark", "personality": "Inventive, witty, unconventional"},
+      "analyst": {"name": "Banner", "personality": "Thoughtful, analytical, evidence-driven"},
+      "executor": {"name": "Ironclad", "personality": "Practical, resourceful, action-oriented"},
+      "challenger": {"name": "Loki", "personality": "Questioning, unpredictable, skeptical"},
+      "specialist": {"name": "Strange", "personality": "Knowledgeable, precise, exploratory"},
+      "communicator": {"name": "Cap", "personality": "Diplomatic, trustworthy, persuasive"},
+      "organizer": {"name": "Widow", "personality": "Organized, discreet, coordinated"},
+      "quality_reviewer": {"name": "Hawkeye", "personality": "Observant, precise, detail-oriented"}
+    }
+  },
+  "professional": {
+    "description": "Plain role titles and business terminology.",
+    "terminology": "professional",
+    "identities": {
+      "leader": {"name": "Lead", "personality": "Clear, structured, decisive"},
+      "researcher": {"name": "Researcher", "personality": "Thorough, neutral, well-sourced"},
+      "creative_thinker": {"name": "Ideation Lead", "personality": "Open, generative, practical"},
+      "analyst": {"name": "Analyst", "personality": "Rigorous, quantitative, cautious"},
+      "executor": {"name": "Builder", "personality": "Pragmatic, reliable, concise"},
+      "challenger": {"name": "Red Team", "personality": "Skeptical, constructive, direct"},
+      "specialist": {"name": "Domain Expert", "personality": "Precise, authoritative, careful"},
+      "communicator": {"name": "Communications", "personality": "Clear, audience-aware, tactful"},
+      "organizer": {"name": "Coordinator", "personality": "Methodical, punctual, structured"},
+      "quality_reviewer": {"name": "QA Reviewer", "personality": "Meticulous, evidence-based, impartial"}
+    }
+  }
+}

package/skill/brainiverse/runtime/evaluation.mjs

@@ -0,0 +1,58 @@
+// Evaluation Engine: evidence-backed reviews and mission metrics.
+import * as orchestrator from "./orchestrator.mjs";
+import { BrainiverseError } from "./store.mjs";
+
+export const VERDICTS = ["pass", "pass_with_issues", "fail"];
+
+/** A review must cite evidence. A pass without evidence is refused, as is reviewing nothing. */
+export function addReview(state, target, verdict, evidence = [], issues = [], reviewer = "leader") {
+  if (!VERDICTS.includes(verdict)) throw new BrainiverseError(`verdict must be one of ${VERDICTS.join(", ")}`);
+  if (!evidence.some((e) => e && e.trim())) throw new BrainiverseError("a review needs evidence: what was checked and how");
+  if (verdict === "fail" && !issues.length) throw new BrainiverseError("a failing review must list the issues");
+  if (target !== "mission") {
+    const task = orchestrator.getTask(state, target);
+    if (!["submitted", "done"].includes(task.status)) {
+      throw new BrainiverseError(`${target} is ${task.status}; there is nothing to review yet`);
+    }
+  }
+  const review = { target, verdict, evidence: [...evidence], issues: [...issues], reviewer, at: orchestrator.now() };
+  state.reviews.push(review);
+  return review;
+}
+
+const round = (n, digits) => Math.round(n * 10 ** digits) / 10 ** digits;
+
+export function metrics(state) {
+  const tasks = Object.values(state.tasks);
+  const invocations = Object.values(state.invocations);
+  const latencies = invocations.filter((i) => i.finished).map((i) => i.finished - i.started).sort((a, b) => a - b);
+  const byAgent = {};
+  for (const i of invocations) byAgent[i.agent] = (byAgent[i.agent] || 0) + 1;
+  const enabled = state.team.agents.filter((a) => a.enabled && a.id !== state.team.leader).map((a) => a.id);
+  const deliverables = tasks.filter((t) => t.kind === "task");
+  const firstTime = deliverables.filter((t) => t.status === "done" && t.iterations === 0 && t.attempts === 1);
+  // Invocations whose output was never used: failed, timed out, cancelled, or superseded by a revision.
+  const unused = invocations.filter((i) => ["failed", "timed_out", "cancelled"].includes(i.status)).length +
+    tasks.reduce((n, t) => n + t.iterations, 0);
+  return {
+    tasks_total: tasks.length,
+    tasks_done: tasks.filter((t) => t.status === "done").length,
+    tasks_failed: tasks.filter((t) => t.status === "failed").length,
+    completion_rate: deliverables.length ? round(deliverables.filter((t) => t.status === "done").length / deliverables.length, 3) : null,
+    first_pass_acceptance: deliverables.length ? round(firstTime.length / deliverables.length, 3) : null,
+    invocations: invocations.length,
+    invocations_by_agent: byAgent,
+    unused_invocations: unused,
+    retries: tasks.reduce((n, t) => n + Math.max(t.attempts - 1, 0), 0),
+    revisions: tasks.reduce((n, t) => n + t.iterations, 0),
+    idle_team_members: enabled.filter((a) => !(a in byAgent)),
+    latency_s: {
+      median: latencies.length ? round(latencies[Math.floor(latencies.length / 2)], 1) : null,
+      max: latencies.length ? round(latencies.at(-1), 1) : null,
+    },
+    tokens: state.usage.tokens,
+    reviews: Object.fromEntries(VERDICTS.map((v) => [v, state.reviews.filter((r) => r.verdict === v).length])),
+    results_with_sources: tasks.filter((t) => t.result && t.result.evidence?.length).length,
+    results_total: tasks.filter((t) => t.result).length,
+  };
+}

package/skill/brainiverse/runtime/meetings.mjs

@@ -0,0 +1,224 @@
+// Meeting Engine: structured discussions between the human, the Leader, and invited agents,
+// plus direct lines (the human talking one-on-one with a single agent).
+//
+// There is deliberately no command for posting a message *as* an agent. Agent contributions
+// enter the transcript only when the agent was actually invoked for a meeting task and
+// submitted a result, so participation can never be fabricated.
+import * as orchestrator from "./orchestrator.mjs";
+import * as teams from "./teams.mjs";
+import { BrainiverseError, nextId } from "./store.mjs";
+
+const { now } = orchestrator;
+
+export function getMeeting(state, meetingId) {
+  if (!(meetingId in state.meetings)) throw new BrainiverseError(`no meeting ${meetingId}`);
+  return state.meetings[meetingId];
+}
+
+function requireOpen(meeting, allowPaused = false) {
+  const allowed = allowPaused ? ["active", "paused"] : ["active"];
+  if (!allowed.includes(meeting.status)) throw new BrainiverseError(`meeting ${meeting.id} is ${meeting.status}`);
+}
+
+function post(meeting, from, kind, text, extra = {}) {
+  const message = { seq: meeting.messages.length + 1, from, kind, text, at: now(), ...extra };
+  meeting.messages.push(message);
+  return message;
+}
+
+function newMeeting(state, fields) {
+  const id = nextId("M", state.meetings);
+  const meeting = {
+    id, mode: "group", status: "active", started: now(), ended: null, messages: [], decisions: [],
+    assumptions: [], questions: [], actions: [], summary: "", ...fields,
+  };
+  state.meetings[id] = meeting;
+  return meeting;
+}
+
+export function start(state, objective, participants) {
+  orchestrator.requireActive(state);
+  if (!objective || !objective.trim()) throw new BrainiverseError("a meeting needs an objective");
+  const leader = state.team.leader;
+  const invited = [...new Set(participants)].filter((p) => p !== leader);
+  if (!invited.length) throw new BrainiverseError("invite at least one agent besides the leader");
+  const limit = state.limits.max_meeting_participants;
+  if (invited.length > limit) {
+    throw new BrainiverseError(`${invited.length} participants exceeds max_meeting_participants (${limit}); ` +
+      "invite only agents who add value");
+  }
+  for (const id of invited) if (!teams.findAgent(state.team, id).enabled) throw new BrainiverseError(`${id} is disabled`);
+  const meeting = newMeeting(state, { objective: objective.trim(), host: leader, participants: invited });
+  const names = invited.map((a) => teams.findAgent(state.team, a).name).join(", ");
+  post(meeting, leader, "system", `Meeting opened: ${meeting.objective}. Participants: ${names}.`);
+  return meeting;
+}
+
+/** A one-on-one conversation between the human and a single agent, without the Leader. */
+export function startDirect(state, agentId, topic = "") {
+  orchestrator.requireActive(state);
+  const profile = teams.findAgent(state.team, agentId);
+  if (!profile.enabled) throw new BrainiverseError(`${profile.name} is disabled`);
+  const meeting = newMeeting(state, {
+    mode: "direct", objective: topic.trim() || `Direct conversation with ${profile.name}`, host: "human",
+    participants: [agentId],
+  });
+  post(meeting, "human", "system", `Direct line opened with ${profile.name}.`);
+  return meeting;
+}
+
+/** The human's message to the agent; creates the task whose real invocation produces the reply. */
+export function directMessage(state, meetingId, text) {
+  const meeting = getMeeting(state, meetingId);
+  if (meeting.mode !== "direct") throw new BrainiverseError(`${meetingId} is a group meeting; use \`meeting human\` there`);
+  requireOpen(meeting);
+  if (!text || !text.trim()) throw new BrainiverseError("message is empty");
+  post(meeting, "human", "human", text);
+  return orchestrator.addTask(state, {
+    objective: `Reply to the human: ${text.trim()}`, agent: meeting.participants[0], kind: "meeting",
+    meeting: meetingId, expected_output: "Your reply to the human, in findings, written as you would say it",
+  });
+}
+
+/** Create a contribution task. The Leader then runs it like any task (start, invoke, submit). */
+export function ask(state, meetingId, agentId, prompt) {
+  const meeting = getMeeting(state, meetingId);
+  requireOpen(meeting);
+  if (meeting.mode === "direct") throw new BrainiverseError(`${meetingId} is a direct line; the human's messages go through \`chat say\``);
+  if (!meeting.participants.includes(agentId)) throw new BrainiverseError(`${agentId} is not in meeting ${meetingId}; add them first`);
+  const task = orchestrator.addTask(state, {
+    objective: prompt, agent: agentId, kind: "meeting", meeting: meetingId,
+    expected_output: "A contribution to the discussion in the result protocol, responding to the transcript",
+  });
+  post(meeting, meeting.host, "request", `@${agentId}: ${prompt}`, { task: task.id });
+  return task;
+}
+
+/** Called when a meeting task is submitted: the real result becomes the agent's message. */
+export function recordContribution(state, task) {
+  const meeting = getMeeting(state, task.meeting);
+  const { findings, recommendations = [], uncertainty = "" } = task.result;
+  const text = typeof findings === "string" ? findings : findings.map((f) => `- ${f}`).join("\n");
+  post(meeting, task.agent, "contribution", text, {
+    task: task.id, invocation: task.invocations.at(-1), recommendations, uncertainty,
+  });
+  task.status = "done"; // a contribution is discussion, not a deliverable awaiting acceptance
+}
+
+export function say(state, meetingId, text) {
+  const meeting = getMeeting(state, meetingId);
+  requireOpen(meeting);
+  if (meeting.mode === "direct") throw new BrainiverseError("the Leader does not speak in a direct line");
+  return post(meeting, meeting.host, "host", text);
+}
+
+const findItem = (items, id) => {
+  const item = items.find((i) => i.id === id);
+  if (!item) throw new BrainiverseError(`no item ${id}`);
+  return item;
+};
+
+export function human(state, meetingId, text, questionId) {
+  const meeting = getMeeting(state, meetingId);
+  requireOpen(meeting, true);
+  const message = post(meeting, "human", "human", text);
+  if (questionId) findItem(meeting.questions, questionId).answer = text;
+  return message;
+}
+
+export function question(state, meetingId, text, to = "human") {
+  const meeting = getMeeting(state, meetingId);
+  requireOpen(meeting);
+  const item = { id: nextId("Q", meeting.questions.map((q) => q.id)), text, to, answer: null };
+  meeting.questions.push(item);
+  post(meeting, meeting.host, "question", text, { question: item.id });
+  return item;
+}
+
+export function decide(state, meetingId, text, approvedByHuman = false) {
+  const meeting = getMeeting(state, meetingId);
+  requireOpen(meeting, true);
+  const decision = {
+    id: nextId("D", state.decisions.map((d) => d.id)), text, meeting: meetingId,
+    approved_by_human: approvedByHuman, at: now(),
+  };
+  meeting.decisions.push(decision.id);
+  state.decisions.push(decision);
+  post(meeting, meeting.host, "decision", text, { decision: decision.id });
+  return decision;
+}
+
+export function assume(state, meetingId, text) {
+  const meeting = getMeeting(state, meetingId);
+  meeting.assumptions.push(text);
+  post(meeting, meeting.host, "assumption", text);
+  return text;
+}
+
+/** Convert a conclusion into a real task on the board. */
+export function action(state, meetingId, agentId, objective, { acceptance = [], depends_on = [] } = {}) {
+  const meeting = getMeeting(state, meetingId);
+  const task = orchestrator.addTask(state, {
+    objective, agent: agentId, acceptance, depends_on,
+    context: `Action item from meeting ${meetingId}: ${meeting.objective}`,
+  });
+  meeting.actions.push(task.id);
+  post(meeting, meeting.host, "action", `${task.id} → ${agentId}: ${objective}`, { task: task.id });
+  return task;
+}
+
+export function addParticipant(state, meetingId, agentId) {
+  const meeting = getMeeting(state, meetingId);
+  requireOpen(meeting, true);
+  if (meeting.mode === "direct") throw new BrainiverseError("a direct line has exactly one agent; start a meeting instead");
+  if (!teams.findAgent(state.team, agentId).enabled) throw new BrainiverseError(`${agentId} is disabled`);
+  if (meeting.participants.includes(agentId)) throw new BrainiverseError(`${agentId} is already in the meeting`);
+  if (meeting.participants.length >= state.limits.max_meeting_participants) {
+    throw new BrainiverseError("meeting is at max_meeting_participants");
+  }
+  meeting.participants.push(agentId);
+  post(meeting, meeting.host, "system", `${agentId} joined.`);
+}
+
+export function removeParticipant(state, meetingId, agentId) {
+  const meeting = getMeeting(state, meetingId);
+  if (!meeting.participants.includes(agentId)) throw new BrainiverseError(`${agentId} is not in the meeting`);
+  meeting.participants = meeting.participants.filter((p) => p !== agentId);
+  for (const task of Object.values(state.tasks)) {
+    if (task.meeting === meetingId && task.agent === agentId && task.status === "pending") {
+      orchestrator.cancel(state, task.id, "participant removed from meeting");
+    }
+  }
+  post(meeting, meeting.host, "system", `${agentId} left.`);
+}
+
+export function setStatus(state, meetingId, status, summary = "") {
+  const meeting = getMeeting(state, meetingId);
+  const transitions = { paused: ["active"], active: ["paused"], ended: ["active", "paused"] };
+  if (!transitions[status].includes(meeting.status)) {
+    throw new BrainiverseError(`cannot move meeting from ${meeting.status} to ${status}`);
+  }
+  if (status === "ended") {
+    if (!summary.trim() && meeting.mode === "direct") summary = "Direct conversation ended.";
+    if (!summary.trim()) throw new BrainiverseError("ending a meeting needs a summary of decisions and open issues");
+    meeting.summary = summary;
+    meeting.ended = now();
+    for (const task of Object.values(state.tasks)) {
+      if (task.meeting === meetingId && task.kind === "meeting" && task.status === "pending") {
+        orchestrator.cancel(state, task.id, "meeting ended");
+      }
+    }
+  }
+  meeting.status = status;
+  post(meeting, meeting.host, "system", `Meeting ${status}.` + (summary ? ` Summary: ${summary}` : ""));
+  return meeting;
+}
+
+export function transcript(state, meetingId, limit = 40) {
+  const meeting = getMeeting(state, meetingId);
+  const names = Object.fromEntries(state.team.agents.map((a) => [a.id, a.name]));
+  names.human = "Human";
+  return meeting.messages.slice(-limit)
+    .map((m) => `[${m.kind}] ${names[m.from] ?? m.from}: ${m.text}`)
+    .join("\n");
+}

package/skill/brainiverse/runtime/memory.mjs

@@ -0,0 +1,115 @@
+// Memory Manager: agent, team, and project memory, plus secret redaction.
+//
+// Scopes:
+//   agent:<id>   role-specific knowledge an agent keeps across missions
+//   team:<id>    shared conventions and team-level decisions
+//   project      goals, findings and decisions for the active mission (stored in mission state)
+//
+// Nothing is remembered automatically. Agents may suggest memories in their results; only the
+// Leader writes them, and records that look like secrets are refused.
+import { now } from "./orchestrator.mjs";
+import { BrainiverseError, checkSlug, nextId, readJson, writeJson } from "./store.mjs";
+
+// The generic "key: value" rule runs first so it consumes the whole value, and never matches a
+// "[redacted ...]" marker left by an earlier rule.
+const SECRET_PATTERNS = [
+  [/\b(?:password|passwd|secret|api[_-]?key|token)\s*[:=]\s*[^\s[]\S{5,}/gi, "credential"],
+  [/\bsk-[A-Za-z0-9_-]{16,}/g, "API key"],
+  [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, "AWS access key"],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}/g, "GitHub token"],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}/g, "Slack token"],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, "private key"],
+  [/\b(?:\d[ -]?){13,16}\b/g, "card number"],
+];
+
+export function findSecrets(text) {
+  const found = new Set();
+  for (const [pattern, label] of SECRET_PATTERNS) {
+    pattern.lastIndex = 0;
+    if (pattern.test(text || "")) found.add(label);
+  }
+  return [...found].sort();
+}
+
+export function redact(text) {
+  if (typeof text !== "string") return text;
+  for (const [pattern, label] of SECRET_PATTERNS) text = text.replace(pattern, `[redacted ${label}]`);
+  return text;
+}
+
+function parseScope(scope) {
+  if (scope === "project") return ["project", null];
+  const [kind, ...rest] = String(scope).split(":");
+  const ref = rest.join(":");
+  if (!["agent", "team"].includes(kind) || !ref) throw new BrainiverseError("scope must be 'project', 'agent:<id>' or 'team:<id>'");
+  return [kind, checkSlug(ref, `${kind} id`)];
+}
+
+const storePath = (ws, kind, ref) => ws.path("memory", `${kind}-${ref}.json`);
+
+function loadScope(ws, scope, state) {
+  const [kind, ref] = parseScope(scope);
+  if (kind === "project") {
+    if (!state) throw new BrainiverseError("project memory needs an active mission");
+    return state.memory;
+  }
+  return readJson(storePath(ws, kind, ref), []);
+}
+
+function saveScope(ws, scope, records, state) {
+  const [kind, ref] = parseScope(scope);
+  if (kind === "project") state.memory = records;
+  else writeJson(storePath(ws, kind, ref), records);
+}
+
+function refuseSecrets(text) {
+  const secrets = findSecrets(text);
+  if (secrets.length) {
+    throw new BrainiverseError(`refusing to store what looks like a ${secrets.join(", ")}; ` +
+      "secrets belong in the environment or a secret manager, not in memory");
+  }
+}
+
+export function add(ws, scope, text, { tags = [], source = "leader", state = null } = {}) {
+  if (!text || !text.trim()) throw new BrainiverseError("memory text is empty");
+  refuseSecrets(text);
+  const records = loadScope(ws, scope, state);
+  const record = { id: nextId("R", records.map((r) => r.id)), text: text.trim(), tags: [...tags], source, created: now() };
+  records.push(record);
+  saveScope(ws, scope, records, state);
+  return record;
+}
+
+export function list(ws, scope, { state = null, tags = [] } = {}) {
+  const records = loadScope(ws, scope, state);
+  return tags.length ? records.filter((r) => r.tags.some((t) => tags.includes(t))) : records;
+}
+
+export function edit(ws, scope, recordId, text, { state = null } = {}) {
+  refuseSecrets(text);
+  const records = loadScope(ws, scope, state);
+  const record = records.find((r) => r.id === recordId);
+  if (!record) throw new BrainiverseError(`no memory record ${recordId} in ${scope}`);
+  record.text = text.trim();
+  record.edited = now();
+  saveScope(ws, scope, records, state);
+  return record;
+}
+
+export function remove(ws, scope, recordId, { state = null } = {}) {
+  const records = loadScope(ws, scope, state);
+  const kept = records.filter((r) => r.id !== recordId);
+  if (kept.length === records.length) throw new BrainiverseError(`no memory record ${recordId} in ${scope}`);
+  saveScope(ws, scope, kept, state);
+}
+
+/** Memory shared with one agent: its own, its team's, and the project's. Never other agents'. */
+export function contextFor(ws, state, agentId, limit = 12) {
+  const agentMemory = agentId ? readJson(storePath(ws, "agent", agentId), []) : [];
+  const teamMemory = readJson(storePath(ws, "team", state.team_ref), []);
+  return {
+    agent: agentMemory.slice(-limit).map((r) => r.text),
+    team: teamMemory.slice(-limit).map((r) => r.text),
+    project: state.memory.slice(-limit).map((r) => r.text),
+  };
+}