oh-my-llmwikimode 1.0.0

package/src/team/queue.js

@@ -0,0 +1,290 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DEFAULT_BUILT_AT,
+  validateAgentGroup,
+  validateAgentProfile,
+  validateEvidenceNote,
+  validateRole,
+  validateTaskCard,
+} from "./schema.js";
+
+const DEFAULT_ROLES = [
+  {
+    id: "builder",
+    label: "Builder",
+    description: "Implements approved tasks and returns evidence.",
+    default_capabilities: ["read", "dispatch"],
+    dispatch_instructions: "Implement only the approved task and return evidence.",
+  },
+  {
+    id: "reviewer",
+    label: "Reviewer",
+    description: "Reviews evidence and flags gaps.",
+    default_capabilities: ["read"],
+    dispatch_instructions: "Review artifacts and report findings only.",
+  },
+];
+
+const DEFAULT_AGENT_PROFILES = [
+  {
+    id: "main-opencode",
+    label: "Main OpenCode",
+    kind: "opencode",
+    default_role_id: "builder",
+    scope: "main",
+    capability_policy: { allowed: ["read", "dispatch"], requires_approval: ["shell", "browser", "network", "sync"], denied: ["git_push", "direct_agent_message"] },
+    dispatch_template: "Use an approval-first implementation packet and return evidence.",
+  },
+  {
+    id: "oracle-reviewer",
+    label: "Oracle Reviewer",
+    kind: "oracle",
+    default_role_id: "reviewer",
+    scope: "sub",
+    capability_policy: { allowed: ["read"], requires_approval: [], denied: ["shell", "git_push", "browser", "network", "sync", "direct_agent_message"] },
+    dispatch_template: "Review only. Do not execute actions.",
+  },
+];
+
+const DEFAULT_AGENT_GROUPS = [
+  {
+    id: "core-team",
+    label: "Core Team",
+    agent_profile_ids: ["main-opencode", "oracle-reviewer"],
+    default_queue_policy: "approval-first",
+    description: "Default local Stage 2 team.",
+  },
+];
+
+const ALLOWED_TRANSITIONS = new Map([
+  ["proposed", new Set(["approved", "blocked"])],
+  ["approved", new Set(["dispatched", "blocked", "proposed"])],
+  ["dispatched", new Set(["evidence", "blocked", "review"])],
+  ["evidence", new Set(["review", "blocked", "done"])],
+  ["review", new Set(["done", "blocked", "evidence"])],
+  ["blocked", new Set(["approved", "dispatched", "review", "done"])],
+  ["done", new Set([])],
+]);
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function atomicWriteJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpFile = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  fs.writeFileSync(tmpFile, JSON.stringify(data, null, 2));
+  fs.renameSync(tmpFile, filePath);
+}
+
+function sortById(items) {
+  return [...items].sort((a, b) => String(a.id).localeCompare(String(b.id)));
+}
+
+function sortTasks(items) {
+  return [...items].sort((a, b) => `${a.created_at}:${a.id}`.localeCompare(`${b.created_at}:${b.id}`));
+}
+
+function normalizeDefaults(items, validator) {
+  return items.map((item) => {
+    const result = validator(item);
+    if (!result.valid) throw new Error(result.errors.join("; "));
+    return result.value;
+  });
+}
+
+function createEmptyQueue() {
+  return {
+    version: 1,
+    agent_profiles: normalizeDefaults(DEFAULT_AGENT_PROFILES, validateAgentProfile),
+    agent_groups: normalizeDefaults(DEFAULT_AGENT_GROUPS, validateAgentGroup),
+    roles: normalizeDefaults(DEFAULT_ROLES, validateRole),
+    tasks: [],
+    evidence_notes: [],
+    meta: { built_at: DEFAULT_BUILT_AT },
+  };
+}
+
+function normalizeQueue(queue) {
+  const base = createEmptyQueue();
+  const profiles = [...base.agent_profiles];
+  const groups = [...base.agent_groups];
+  const roles = [...base.roles];
+  const tasks = [];
+  const evidenceNotes = [];
+
+  for (const profile of Array.isArray(queue?.agent_profiles) ? queue.agent_profiles : []) {
+    const result = validateAgentProfile(profile);
+    if (result.valid) profiles.push(result.value);
+  }
+  for (const group of Array.isArray(queue?.agent_groups) ? queue.agent_groups : []) {
+    const result = validateAgentGroup(group);
+    if (result.valid) groups.push(result.value);
+  }
+  for (const role of Array.isArray(queue?.roles) ? queue.roles : []) {
+    const result = validateRole(role);
+    if (result.valid) roles.push(result.value);
+  }
+  for (const task of Array.isArray(queue?.tasks) ? queue.tasks : []) {
+    const result = validateTaskCard(task);
+    if (result.valid) tasks.push(result.value);
+  }
+  for (const note of Array.isArray(queue?.evidence_notes) ? queue.evidence_notes : []) {
+    const result = validateEvidenceNote(note);
+    if (result.valid) evidenceNotes.push(result.value);
+  }
+
+  return {
+    version: 1,
+    agent_profiles: sortById([...new Map(profiles.map((item) => [item.id, item])).values()]),
+    agent_groups: sortById([...new Map(groups.map((item) => [item.id, item])).values()]),
+    roles: sortById([...new Map(roles.map((item) => [item.id, item])).values()]),
+    tasks: sortTasks([...new Map(tasks.map((item) => [item.id, item])).values()]),
+    evidence_notes: sortById([...new Map(evidenceNotes.map((item) => [item.id, item])).values()]),
+    meta: { built_at: queue?.meta?.built_at || DEFAULT_BUILT_AT },
+  };
+}
+
+function writeQueue(wikiRoot, queue) {
+  const normalized = normalizeQueue({ ...queue, meta: { built_at: nowIso() } });
+  atomicWriteJson(getAgentTeamPaths(wikiRoot).queueFile, normalized);
+  return normalized;
+}
+
+function appendAudit(wikiRoot, action, entry = {}, options = {}) {
+  const paths = getAgentTeamPaths(wikiRoot);
+  fs.mkdirSync(paths.root, { recursive: true });
+  const record = {
+    timestamp: nowIso(),
+    action,
+    actor: options.actor || "system",
+    ...entry,
+  };
+  fs.appendFileSync(paths.auditFile, `${JSON.stringify(record)}\n`);
+  return record;
+}
+
+function result(success, payload = {}) {
+  return { success, ...payload };
+}
+
+export function getAgentTeamPaths(wikiRoot) {
+  const systemDir = path.join(wikiRoot, ".system");
+  const root = path.join(systemDir, "agent-team");
+  return {
+    systemDir,
+    root,
+    queueFile: path.join(root, "queue.json"),
+    dispatchDir: path.join(root, "dispatch-packets"),
+    auditFile: path.join(root, "audit.jsonl"),
+  };
+}
+
+export function ensureAgentTeamStructure(wikiRoot) {
+  const paths = getAgentTeamPaths(wikiRoot);
+  fs.mkdirSync(paths.root, { recursive: true });
+  fs.mkdirSync(paths.dispatchDir, { recursive: true });
+  if (!fs.existsSync(paths.queueFile)) writeQueue(wikiRoot, createEmptyQueue());
+  return paths;
+}
+
+export function readAgentTeamQueue(wikiRoot) {
+  const paths = ensureAgentTeamStructure(wikiRoot);
+  try {
+    return normalizeQueue(JSON.parse(fs.readFileSync(paths.queueFile, "utf-8")));
+  } catch {
+    return createEmptyQueue();
+  }
+}
+
+export function createAgentProfile(wikiRoot, profile, options = {}) {
+  const validation = validateAgentProfile(profile);
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  const queue = readAgentTeamQueue(wikiRoot);
+  queue.agent_profiles = [...queue.agent_profiles.filter((item) => item.id !== validation.value.id), validation.value];
+  writeQueue(wikiRoot, queue);
+  appendAudit(wikiRoot, "create_agent_profile", { agent_profile_id: validation.value.id }, options);
+  return result(true, { profile: validation.value });
+}
+
+export function createAgentGroup(wikiRoot, group, options = {}) {
+  const validation = validateAgentGroup(group);
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  const queue = readAgentTeamQueue(wikiRoot);
+  queue.agent_groups = [...queue.agent_groups.filter((item) => item.id !== validation.value.id), validation.value];
+  writeQueue(wikiRoot, queue);
+  appendAudit(wikiRoot, "create_agent_group", { agent_group_id: validation.value.id }, options);
+  return result(true, { group: validation.value });
+}
+
+export function createTaskCard(wikiRoot, task, options = {}) {
+  const validation = validateTaskCard({ ...task, created_at: task.created_at || nowIso(), updated_at: task.updated_at || nowIso() });
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  const queue = readAgentTeamQueue(wikiRoot);
+  queue.tasks = [...queue.tasks.filter((item) => item.id !== validation.value.id), validation.value];
+  writeQueue(wikiRoot, queue);
+  appendAudit(wikiRoot, "create_task", { task_id: validation.value.id, summary: validation.value.title }, options);
+  return result(true, { task: validation.value });
+}
+
+export function updateTaskStatus(wikiRoot, taskId, status, options = {}) {
+  const queue = readAgentTeamQueue(wikiRoot);
+  const task = queue.tasks.find((item) => item.id === taskId);
+  if (!task) return result(false, { error: `Task not found: ${taskId}` });
+
+  let targetStatus;
+  try {
+    targetStatus = validateTaskCard({ ...task, status, blocked_reason: options.blocked_reason || task.blocked_reason }).value.status;
+  } catch (error) {
+    return result(false, { error: error.message });
+  }
+
+  if (targetStatus === "blocked" && !options.blocked_reason && !task.blocked_reason) {
+    return result(false, { error: "Blocked tasks require blocked_reason" });
+  }
+  if (targetStatus === "approved" && !options.approval && !task.approval) {
+    return result(false, { error: "Approval metadata is required" });
+  }
+  if (targetStatus === "dispatched" && !task.approval && !options.approval) {
+    return result(false, { error: "Dispatch requires approval metadata" });
+  }
+  if (!ALLOWED_TRANSITIONS.get(task.status)?.has(targetStatus)) {
+    return result(false, { error: `Unsafe transition rejected: ${task.status} -> ${targetStatus}` });
+  }
+
+  const updated = {
+    ...task,
+    status: targetStatus,
+    updated_at: nowIso(),
+    ...(options.approval ? { approval: options.approval } : {}),
+    ...(options.blocked_reason ? { blocked_reason: options.blocked_reason } : {}),
+  };
+  const validation = validateTaskCard(updated);
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+
+  queue.tasks = queue.tasks.map((item) => item.id === taskId ? validation.value : item);
+  writeQueue(wikiRoot, queue);
+  appendAudit(wikiRoot, "update_task_status", { task_id: taskId, status: targetStatus }, options);
+  return result(true, { task: validation.value });
+}
+
+export function appendTaskEvidence(wikiRoot, taskId, evidence, options = {}) {
+  const queue = readAgentTeamQueue(wikiRoot);
+  const task = queue.tasks.find((item) => item.id === taskId);
+  if (!task) return result(false, { error: `Task not found: ${taskId}` });
+  if (task.status !== "dispatched" && task.status !== "review") {
+    return result(false, { error: "Evidence can only be attached after dispatched or during review" });
+  }
+  if (!task.approval) return result(false, { error: "Evidence requires approval metadata" });
+
+  const validation = validateEvidenceNote({ ...evidence, task_id: taskId });
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  queue.evidence_notes = [...queue.evidence_notes.filter((item) => item.id !== validation.value.id), validation.value];
+  queue.tasks = queue.tasks.map((item) => item.id === taskId
+    ? { ...item, status: "evidence", updated_at: nowIso() }
+    : item);
+  writeQueue(wikiRoot, queue);
+  appendAudit(wikiRoot, "append_evidence", { task_id: taskId, evidence_id: validation.value.id, summary: validation.value.summary }, options);
+  return result(true, { evidence: validation.value });
+}

package/src/team/schema.js

@@ -0,0 +1,225 @@
+import { redactSecrets } from "../security.js";
+
+export const QUEUE_STATUSES = ["proposed", "approved", "dispatched", "evidence", "review", "done", "blocked"];
+export const AGENT_SCOPES = ["main", "sub", "custom"];
+export const DEFAULT_BUILT_AT = "1970-01-01T00:00:00.000Z";
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeScalar(value, maxLength = 500) {
+  return redactTeamText(String(value ?? "")
+    .replace(/\r?\n/g, " ")
+    .replace(/\s+/g, " ")
+    .trim())
+    .slice(0, maxLength);
+}
+
+function normalizeId(value, label = "id") {
+  const id = normalizeScalar(value, 120).toLowerCase();
+  if (!/^[a-z0-9][a-z0-9_-]{0,119}$/.test(id)) {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+  return id;
+}
+
+function normalizeStringList(value, maxLength = 120) {
+  const values = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+  return [...new Set(values.map((item) => normalizeScalar(item, maxLength)).filter(Boolean))]
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeSafeRelativePath(value, label = "path", maxLength = 240) {
+  const normalized = normalizeScalar(value, maxLength).replace(/\\/g, "/");
+  if (!normalized) return "";
+  if (/^[a-z]:\//i.test(normalized) || normalized.startsWith("/") || normalized.startsWith("//")) {
+    throw new Error(`Unsafe ${label}: absolute paths are not allowed`);
+  }
+  if (normalized.split("/").some((segment) => segment === "..")) {
+    throw new Error(`Unsafe ${label}: traversal is not allowed`);
+  }
+  return normalized;
+}
+
+function normalizeArtifactList(value) {
+  const values = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+  return [...new Set(values.map((item) => normalizeSafeRelativePath(item, "artifact path", 240)).filter(Boolean))]
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeContextRefs(value) {
+  const refs = Array.isArray(value) ? value : [];
+  return refs.flatMap((ref) => {
+    if (!isRecord(ref)) return [];
+    const type = normalizeScalar(ref.type, 40).toLowerCase();
+    const path = normalizeSafeRelativePath(ref.path, "context reference path", 240);
+    const query = normalizeScalar(ref.query, 240);
+    const graphId = normalizeSafeRelativePath(ref.graph_id || ref.graphId, "graph reference", 240);
+    if (!type || (!path && !query && !graphId)) return [];
+    return [{ type, ...(path ? { path } : {}), ...(query ? { query } : {}), ...(graphId ? { graph_id: graphId } : {}) }];
+  }).sort((a, b) => `${a.type}:${a.path || a.query || a.graph_id}`.localeCompare(`${b.type}:${b.path || b.query || b.graph_id}`));
+}
+
+function normalizeApproval(value) {
+  if (!isRecord(value)) return null;
+  const approvedBy = normalizeScalar(value.approved_by || value.approvedBy, 120);
+  const approvedAt = normalizeScalar(value.approved_at || value.approvedAt, 80);
+  return {
+    approved_by: approvedBy,
+    approved_at: approvedAt,
+    approved_capabilities: normalizeStringList(value.approved_capabilities || value.approvedCapabilities, 80),
+  };
+}
+
+function validationResult(builder) {
+  try {
+    return { valid: true, value: builder(), errors: [] };
+  } catch (error) {
+    return { valid: false, value: null, errors: [error.message] };
+  }
+}
+
+export function redactTeamText(value) {
+  return redactSecrets(String(value ?? ""));
+}
+
+export function normalizeAgentScope(input) {
+  const scope = normalizeScalar(input || "custom", 40).toLowerCase();
+  if (!AGENT_SCOPES.includes(scope)) {
+    throw new Error(`Invalid agent scope: ${input}`);
+  }
+  return scope;
+}
+
+export function normalizeQueueStatus(input) {
+  const status = normalizeScalar(input || "proposed", 40).toLowerCase();
+  if (!QUEUE_STATUSES.includes(status)) {
+    throw new Error(`Invalid queue status: ${input}`);
+  }
+  return status;
+}
+
+export function normalizeCapabilityPolicy(value = {}) {
+  const policy = isRecord(value) ? value : {};
+  return {
+    allowed: normalizeStringList(policy.allowed, 80),
+    requires_approval: normalizeStringList(policy.requires_approval || policy.requiresApproval, 80),
+    denied: normalizeStringList(policy.denied, 80),
+  };
+}
+
+export function validateAgentProfile(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Agent profile must be an object");
+    const profile = {
+      id: normalizeId(input.id, "agent profile id"),
+      label: normalizeScalar(input.label, 160),
+      kind: normalizeScalar(input.kind || "custom", 80).toLowerCase(),
+      default_role_id: normalizeId(input.default_role_id || input.defaultRoleId || "custom", "default role id"),
+      scope: normalizeAgentScope(input.scope),
+      capability_policy: normalizeCapabilityPolicy(input.capability_policy || input.capabilityPolicy),
+      dispatch_template: normalizeScalar(input.dispatch_template || input.dispatchTemplate, 2000),
+    };
+    if (!profile.label) throw new Error("Agent profile label is required");
+    return profile;
+  });
+}
+
+export function validateAgentGroup(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Agent group must be an object");
+    const group = {
+      id: normalizeId(input.id, "agent group id"),
+      label: normalizeScalar(input.label, 160),
+      agent_profile_ids: normalizeStringList(input.agent_profile_ids || input.agentProfileIds, 120).map((item) => normalizeId(item, "agent profile id")),
+      default_queue_policy: normalizeScalar(input.default_queue_policy || input.defaultQueuePolicy || "approval-first", 120),
+      description: normalizeScalar(input.description, 1000),
+    };
+    if (!group.label) throw new Error("Agent group label is required");
+    return group;
+  });
+}
+
+export function validateRole(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Role must be an object");
+    const role = {
+      id: normalizeId(input.id, "role id"),
+      label: normalizeScalar(input.label, 160),
+      description: normalizeScalar(input.description, 1000),
+      default_capabilities: normalizeStringList(input.default_capabilities || input.defaultCapabilities, 80),
+      dispatch_instructions: normalizeScalar(input.dispatch_instructions || input.dispatchInstructions, 2000),
+    };
+    if (!role.label) throw new Error("Role label is required");
+    return role;
+  });
+}
+
+export function validateTaskCard(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Task card must be an object");
+    const now = new Date(0).toISOString();
+    const task = {
+      id: normalizeId(input.id, "task id"),
+      title: normalizeScalar(input.title, 220),
+      status: normalizeQueueStatus(input.status),
+      role_id: normalizeId(input.role_id || input.roleId || "custom", "role id"),
+      agent_profile_id: normalizeId(input.agent_profile_id || input.agentProfileId || "custom-agent", "agent profile id"),
+      goal: normalizeScalar(input.goal, 2000),
+      success_criteria: normalizeStringList(input.success_criteria || input.successCriteria, 400),
+      context_refs: normalizeContextRefs(input.context_refs || input.contextRefs),
+      capability_request: normalizeStringList(input.capability_request || input.capabilityRequest, 80),
+      approval: normalizeApproval(input.approval),
+      blocked_reason: normalizeScalar(input.blocked_reason || input.blockedReason, 500),
+      created_at: normalizeScalar(input.created_at || input.createdAt || now, 80),
+      updated_at: normalizeScalar(input.updated_at || input.updatedAt || now, 80),
+    };
+    if (!task.title) throw new Error("Task title is required");
+    if (!task.goal) throw new Error("Task goal is required");
+    if (task.success_criteria.length === 0) throw new Error("Task success criteria are required");
+    if (task.status === "blocked" && !task.blocked_reason) throw new Error("Blocked tasks require blocked_reason");
+    return task;
+  });
+}
+
+export function validateDispatchPacket(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Dispatch packet must be an object");
+    const approval = normalizeApproval(input.approval);
+    if (!approval || !approval.approved_by || !approval.approved_at) {
+      throw new Error("Dispatch packet approval metadata is required");
+    }
+    const packet = {
+      id: normalizeId(input.id, "dispatch packet id"),
+      task_id: normalizeId(input.task_id || input.taskId, "task id"),
+      role_id: normalizeId(input.role_id || input.roleId, "role id"),
+      agent_profile_id: normalizeId(input.agent_profile_id || input.agentProfileId, "agent profile id"),
+      allowed_capabilities: normalizeStringList(input.allowed_capabilities || input.allowedCapabilities, 80),
+      forbidden_capabilities: normalizeStringList(input.forbidden_capabilities || input.forbiddenCapabilities, 80),
+      context_refs: normalizeContextRefs(input.context_refs || input.contextRefs),
+      prompt: normalizeScalar(input.prompt, 6000),
+      expected_output: normalizeScalar(input.expected_output || input.expectedOutput, 1000),
+      approval,
+      created_at: normalizeScalar(input.created_at || input.createdAt || new Date(0).toISOString(), 80),
+    };
+    if (!packet.prompt) throw new Error("Dispatch packet prompt is required");
+    return packet;
+  });
+}
+
+export function validateEvidenceNote(input) {
+  return validationResult(() => {
+    if (!isRecord(input)) throw new Error("Evidence note must be an object");
+    const note = {
+      id: normalizeId(input.id, "evidence note id"),
+      task_id: normalizeId(input.task_id || input.taskId, "task id"),
+      agent_profile_id: normalizeId(input.agent_profile_id || input.agentProfileId || "custom-agent", "agent profile id"),
+      summary: normalizeScalar(input.summary, 2000),
+      artifacts: normalizeArtifactList(input.artifacts),
+      created_at: normalizeScalar(input.created_at || input.createdAt || new Date(0).toISOString(), 80),
+    };
+    if (!note.summary) throw new Error("Evidence summary is required");
+    return note;
+  });
+}