Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

42.1 KB
Raw Blame
/**
 * The organization files — parsing, validation and canonical serialization. Pure string
 * work, no I/O: the store reads and writes, the service decides.
 *
 * Intent files (`org_config.toml`, `org_chart.yaml`, calendar events, tickets, the
 * handbook, `channel.toml`) are edited by people and employees; the API is a validating
 * writer over the same format, so a hand-edited file and an API-written one parse under one
 * set of rules. Fact files (`desks.toml`, a ticket's `sessions` and `history` fields,
 * message lines) are written by the server only. An invalid file is reported, never
 * repaired in place.
 */
import path from "node:path";
import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
import {
  Document as YamlDocument,
  isMap,
  isSeq,
  parse as parseYaml,
  stringify as stringifyYaml,
} from "yaml";
import type {
  OrgApprovalMode,
  OrgChannelMessage,
  OrgChannelNoticeKind,
  OrgLanguage,
  OrgStatus,
  OrgTicketHistoryAction,
  OrgTicketHistoryEntry,
  OrgTicketPriority,
  OrgTicketStatus,
} from "../api/types.js";
import { parseScheduleFile } from "../runtime/schedule-file.js";
import type { ScheduleDefinition } from "../runtime/schedule-file.js";
import { SEMANTIC_ID_PATTERN } from "../services/ids.js";
import { DEFAULT_CHANNEL_ID, ceoAgentId, isTicketColumn } from "./paths.js";
import { parsePrincipal } from "./principal.js";
import { isValidTimeZone } from "./zoned.js";

export type ParseResult<T> = { ok: true; value: T } | { ok: false; error: string };

const fail = (error: string): { ok: false; error: string } => ({ ok: false, error });

// ---------------------------------------------------------------------------
// org_config.toml
// ---------------------------------------------------------------------------

export interface OrgConfig {
  name: string;
  mission: string;
  status: OrgStatus;
  timezone: string;
  approvalMode: OrgApprovalMode;
  mentionChainLimit: number;
  budgetWarnRatio: number;
  budgetPauseRatio: number;
  createdBy: string;
  /** The shared workspace root when it is not the organization's own `workspace/`: an absolute directory that exists. */
  workspace?: string;
  /** The model desks and ticket sessions run on when the employee entry names none; absent = the Project default. */
  model?: { provider: string; modelId: string };
  /** The working language everything the organization produces is written in; absent = detected from the mission ({@link orgLanguage}). */
  language?: OrgLanguage;
}

/**
 * The language of a piece of text as the organization uses it: one Han character anywhere
 * makes it Chinese, everything else is English. Deliberately coarse — a mission is one or
 * two sentences, and the question it answers is which of the two sets of templates the
 * company writes in, not what locale it is in.
 */
export function detectLanguage(text: string): OrgLanguage {
  return /\p{Script=Han}/u.test(text) ? "zh" : "en";
}

/**
 * The organization's effective working language: the field when it is set, else the
 * language of the mission. An organization written before the field existed therefore
 * needs no migration — it reads as whatever its mission is written in.
 */
export function orgLanguage(config: OrgConfig): OrgLanguage {
  return config.language ?? detectLanguage(config.mission);
}

/**
 * The bounds `parseOrgConfig` holds the two numeric settings to. Exported because the write
 * path has to refuse exactly what the loader would: a value past them is written happily and
 * then fails to parse on the next load, which marks the organization invalid and stops every
 * automatic trigger until somebody edits the file by hand.
 */
export const MENTION_CHAIN_LIMIT_MAX = 100;
export const BUDGET_RATIO_MAX = 10;

export const ORG_CONFIG_DEFAULTS = {
  status: "active" as OrgStatus,
  approvalMode: "allow-all" as OrgApprovalMode,
  mentionChainLimit: 3,
  budgetWarnRatio: 0.8,
  budgetPauseRatio: 1.0,
};

/**
 * The CEO's monthly budget in USD when organization creation names none. Budgets are
 * compared on the cumulative line — the employee plus every subordinate — so the CEO's
 * budget is the whole company's: a new organization is capped rather than unbounded, and
 * the number is raised (or cleared) once the board knows what the mission costs.
 */
export const DEFAULT_CEO_BUDGET = 100;

function tomlTable(raw: string): ParseResult<Record<string, unknown>> {
  let parsed: unknown;
  try {
    parsed = parseToml(raw);
  } catch (err) {
    return fail(`Failed to parse TOML: ${err instanceof Error ? err.message : String(err)}`);
  }
  if (parsed === null || typeof parsed !== "object") return fail("Content is not a TOML table");
  return { ok: true, value: parsed as Record<string, unknown> };
}

export function parseOrgConfig(raw: string): ParseResult<OrgConfig> {
  const t = tomlTable(raw);
  if (!t.ok) return t;
  const table = t.value;
  const name = table["name"];
  if (typeof name !== "string" || name.trim() === "")
    return fail("name must be a non-empty string");
  const mission = table["mission"];
  if (typeof mission !== "string") return fail("mission must be a string");
  const status = table["status"] ?? ORG_CONFIG_DEFAULTS.status;
  if (status !== "active" && status !== "paused") return fail("status must be active or paused");
  const timezone = table["timezone"] ?? "UTC";
  if (typeof timezone !== "string" || !isValidTimeZone(timezone)) {
    return fail("timezone must be a valid IANA timezone");
  }
  const approvalMode = table["approval_mode"] ?? ORG_CONFIG_DEFAULTS.approvalMode;
  if (approvalMode !== "allow-all" && approvalMode !== "read-only" && approvalMode !== "deny-all") {
    return fail("approval_mode must be allow-all, read-only or deny-all");
  }
  const limit = table["mention_chain_limit"] ?? ORG_CONFIG_DEFAULTS.mentionChainLimit;
  if (
    typeof limit !== "number" ||
    !Number.isInteger(limit) ||
    limit < 0 ||
    limit > MENTION_CHAIN_LIMIT_MAX
  ) {
    return fail(`mention_chain_limit must be an integer between 0 and ${MENTION_CHAIN_LIMIT_MAX}`);
  }
  const warn = table["budget_warn_ratio"] ?? ORG_CONFIG_DEFAULTS.budgetWarnRatio;
  const pause = table["budget_pause_ratio"] ?? ORG_CONFIG_DEFAULTS.budgetPauseRatio;
  for (const [key, v] of [
    ["budget_warn_ratio", warn],
    ["budget_pause_ratio", pause],
  ] as const) {
    if (typeof v !== "number" || !(v > 0) || v > BUDGET_RATIO_MAX)
      return fail(`${key} must be a number in (0, ${BUDGET_RATIO_MAX}]`);
  }
  const createdBy = table["created_by"];
  if (typeof createdBy !== "string" || createdBy === "")
    return fail("created_by must be a non-empty string");
  const workspace = table["workspace"];
  if (workspace !== undefined && (typeof workspace !== "string" || !path.isAbsolute(workspace))) {
    return fail("workspace must be an absolute path");
  }
  const language = table["language"];
  if (language !== undefined && language !== "zh" && language !== "en") {
    return fail("language must be zh or en");
  }
  let model: { provider: string; modelId: string } | undefined;
  if (table["model"] !== undefined) {
    const m = table["model"];
    if (m === null || typeof m !== "object") return fail("model must be a table");
    const provider = (m as Record<string, unknown>)["provider"];
    const modelId = (m as Record<string, unknown>)["model_id"];
    if (
      typeof provider !== "string" ||
      provider === "" ||
      typeof modelId !== "string" ||
      modelId === ""
    ) {
      return fail("model needs both provider and model_id");
    }
    model = { provider, modelId };
  }
  return {
    ok: true,
    value: {
      name: name.trim(),
      mission: mission.trim(),
      status,
      timezone,
      approvalMode,
      mentionChainLimit: limit,
      budgetWarnRatio: warn as number,
      budgetPauseRatio: pause as number,
      createdBy,
      ...(typeof workspace === "string" ? { workspace } : {}),
      ...(model !== undefined ? { model } : {}),
      ...(language !== undefined ? { language } : {}),
    },
  };
}

export function serializeOrgConfig(cfg: OrgConfig): string {
  const table = {
    name: cfg.name,
    mission: cfg.mission,
    status: cfg.status,
    timezone: cfg.timezone,
    approval_mode: cfg.approvalMode,
    mention_chain_limit: cfg.mentionChainLimit,
    budget_warn_ratio: cfg.budgetWarnRatio,
    budget_pause_ratio: cfg.budgetPauseRatio,
    created_by: cfg.createdBy,
    ...(cfg.language !== undefined ? { language: cfg.language } : {}),
    ...(cfg.workspace !== undefined ? { workspace: cfg.workspace } : {}),
    ...(cfg.model !== undefined
      ? { model: { provider: cfg.model.provider, model_id: cfg.model.modelId } }
      : {}),
  };
  return [
    "# org_config.toml — organization settings (the id is the directory name and never changes).",
    "# status: active | paused (paused stops every automatic trigger; people can still talk to any desk).",
    "# approval_mode: allow-all | read-only | deny-all for desk and ticket sessions.",
    "# language: zh | en — the working language of everything the organization writes (optional; detected from the mission when absent).",
    "# workspace: an absolute directory used as the shared workspace instead of ./workspace (optional).",
    "# [model]: provider + model_id for desks and ticket sessions when the employee names none (optional).",
    stringifyToml(table),
    "",
  ].join("\n");
}

// ---------------------------------------------------------------------------
// org_chart.yaml
// ---------------------------------------------------------------------------

export interface OrgEmployee {
  agentId: string;
  title: string;
  /** null for the CEO, the root. */
  reportsTo: string | null;
  duties?: string;
  /** A sub-directory of the shared workspace (`.` = all of it) or an absolute path. */
  workspace: string;
  budget?: number;
  model?: { provider: string; modelId: string };
}

export interface OrgChart {
  employees: OrgEmployee[];
}

function employeeFrom(item: unknown, index: number): ParseResult<OrgEmployee> {
  if (item === null || typeof item !== "object")
    return fail(`employees[${index}] is not a mapping`);
  const e = item as Record<string, unknown>;
  const agentId = e["agent_id"];
  if (typeof agentId !== "string" || !SEMANTIC_ID_PATTERN.test(agentId)) {
    return fail(`employees[${index}].agent_id is missing or not a valid Agent id`);
  }
  const title = e["title"];
  if (typeof title !== "string" || title.trim() === "") {
    return fail(`${agentId}: title must be a non-empty string`);
  }
  const reportsTo = e["reports_to"] ?? null;
  if (reportsTo !== null && (typeof reportsTo !== "string" || reportsTo === "")) {
    return fail(`${agentId}: reports_to must be an Agent id or null`);
  }
  const duties = e["duties"];
  if (duties !== undefined && typeof duties !== "string")
    return fail(`${agentId}: duties must be a string`);
  const workspace = e["workspace"] ?? ".";
  if (typeof workspace !== "string" || workspace.trim() === "") {
    return fail(`${agentId}: workspace must be a non-empty string`);
  }
  const budget = e["budget"];
  if (budget !== undefined && budget !== null && (typeof budget !== "number" || !(budget >= 0))) {
    return fail(`${agentId}: budget must be a number >= 0`);
  }
  let model: { provider: string; modelId: string } | undefined;
  if (e["model"] !== undefined && e["model"] !== null) {
    const m = e["model"];
    if (m === null || typeof m !== "object") return fail(`${agentId}: model must be a mapping`);
    const provider = (m as Record<string, unknown>)["provider"];
    const modelId = (m as Record<string, unknown>)["model_id"];
    if (
      typeof provider !== "string" ||
      provider === "" ||
      typeof modelId !== "string" ||
      modelId === ""
    ) {
      return fail(`${agentId}: model needs both provider and model_id`);
    }
    model = { provider, modelId };
  }
  return {
    ok: true,
    value: {
      agentId,
      title: title.trim(),
      reportsTo: reportsTo as string | null,
      ...(typeof duties === "string" && duties.trim() !== "" ? { duties: duties.trim() } : {}),
      workspace: workspace.trim(),
      ...(typeof budget === "number" ? { budget } : {}),
      ...(model !== undefined ? { model } : {}),
    },
  };
}

/**
 * Parse and validate the employee tree: unique valid ids, exactly one root and it is the
 * CEO (`<orgId>_ceo`), every `reports_to` names another employee, and no cycles — every
 * employee walks up to the root.
 */
export function parseOrgChart(raw: string, orgId: string): ParseResult<OrgChart> {
  let parsed: unknown;
  try {
    parsed = parseYaml(raw);
  } catch (err) {
    return fail(`Failed to parse YAML: ${err instanceof Error ? err.message : String(err)}`);
  }
  if (parsed === null || typeof parsed !== "object") return fail("Content is not a YAML mapping");
  const list = (parsed as Record<string, unknown>)["employees"];
  if (!Array.isArray(list)) return fail("employees must be a list");
  const employees: OrgEmployee[] = [];
  const seen = new Set<string>();
  for (const [i, item] of list.entries()) {
    const r = employeeFrom(item, i);
    if (!r.ok) return r;
    if (seen.has(r.value.agentId)) return fail(`duplicate employee: ${r.value.agentId}`);
    seen.add(r.value.agentId);
    employees.push(r.value);
  }
  const roots = employees.filter((e) => e.reportsTo === null);
  if (roots.length !== 1) return fail("exactly one employee must have reports_to: null (the CEO)");
  if (roots[0]!.agentId !== ceoAgentId(orgId)) {
    return fail(`the root employee must be the CEO ${ceoAgentId(orgId)}`);
  }
  for (const e of employees) {
    if (e.reportsTo === null) continue;
    if (e.reportsTo === e.agentId) return fail(`${e.agentId} reports to itself`);
    if (!seen.has(e.reportsTo))
      return fail(`${e.agentId} reports to unknown employee ${e.reportsTo}`);
  }
  const byId = new Map(employees.map((e) => [e.agentId, e]));
  for (const e of employees) {
    let cur: OrgEmployee | undefined = e;
    for (let steps = 0; cur && cur.reportsTo !== null; steps++) {
      if (steps > employees.length) return fail(`reporting line of ${e.agentId} forms a cycle`);
      cur = byId.get(cur.reportsTo);
    }
  }
  return { ok: true, value: { employees } };
}

export function serializeOrgChart(chart: OrgChart): string {
  const doc = {
    employees: chart.employees.map((e) => ({
      agent_id: e.agentId,
      title: e.title,
      reports_to: e.reportsTo,
      ...(e.duties !== undefined ? { duties: e.duties } : {}),
      workspace: e.workspace,
      ...(e.budget !== undefined ? { budget: e.budget } : {}),
      ...(e.model !== undefined
        ? { model: { provider: e.model.provider, model_id: e.model.modelId } }
        : {}),
    })),
  };
  return [
    "# org_chart.yaml — the employee tree: one employee is one Agent (no Agent, no position),",
    "# joined by reports_to into a tree rooted at the CEO. Budgets are monthly USD caps for an",
    "# employee plus every subordinate; workspace is a sub-directory of the shared workspace",
    "# (. = all of it) or an absolute path that already exists.",
    stringifyYaml(doc, { lineWidth: 0 }).trimEnd(),
    "",
  ].join("\n");
}

/** Every employee below `agentId` (children, grandchildren, …), in tree order. */
export function subordinatesOf(chart: OrgChart, agentId: string): string[] {
  const out: string[] = [];
  const walk = (id: string): void => {
    for (const e of chart.employees) {
      if (e.reportsTo === id) {
        out.push(e.agentId);
        walk(e.agentId);
      }
    }
  };
  walk(agentId);
  return out;
}

/** The reporting line above `agentId`, nearest first, ending at the root. */
export function ancestorsOf(chart: OrgChart, agentId: string): string[] {
  const byId = new Map(chart.employees.map((e) => [e.agentId, e]));
  const out: string[] = [];
  let cur = byId.get(agentId);
  while (cur && cur.reportsTo !== null && out.length <= chart.employees.length) {
    out.push(cur.reportsTo);
    cur = byId.get(cur.reportsTo);
  }
  return out;
}

// ---------------------------------------------------------------------------
// desks.toml (fact file)
// ---------------------------------------------------------------------------

export interface DeskEntry {
  sessionId: string;
  /** The resolved absolute workspace the session was opened in (immutable per session). */
  workspace: string;
  openedAt: string;
  /** Earlier desk sessions of this employee (renewals), oldest first: they still count toward the employee's cost. */
  previous: string[];
}

export type Desks = Record<string, DeskEntry>;

export function parseDesks(raw: string): ParseResult<Desks> {
  const t = tomlTable(raw);
  if (!t.ok) return t;
  const desks: Desks = {};
  for (const [agentId, value] of Object.entries(t.value)) {
    if (value === null || typeof value !== "object") return fail(`${agentId} is not a table`);
    const d = value as Record<string, unknown>;
    if (typeof d["session_id"] !== "string" || typeof d["workspace"] !== "string") {
      return fail(`${agentId}: session_id and workspace are required`);
    }
    const openedAt = d["opened_at"];
    const previous = d["previous"];
    if (
      previous !== undefined &&
      (!Array.isArray(previous) || previous.some((p) => typeof p !== "string"))
    ) {
      return fail(`${agentId}: previous must be a list of session ids`);
    }
    desks[agentId] = {
      sessionId: d["session_id"],
      workspace: d["workspace"],
      openedAt:
        openedAt instanceof Date
          ? openedAt.toISOString()
          : typeof openedAt === "string"
            ? openedAt
            : "",
      previous: (previous as string[] | undefined) ?? [],
    };
  }
  return { ok: true, value: desks };
}

export function serializeDesks(desks: Desks): string {
  const table: Record<string, unknown> = {};
  for (const [agentId, d] of Object.entries(desks)) {
    table[agentId] = {
      session_id: d.sessionId,
      workspace: d.workspace,
      opened_at: d.openedAt,
      ...(d.previous.length > 0 ? { previous: d.previous } : {}),
    };
  }
  return [
    "# desks.toml — desk ledger (a fact file the server writes): employee -> current desk session.",
    stringifyToml(table),
    "",
  ].join("\n");
}

// ---------------------------------------------------------------------------
// calendar/<agent_id>/<name>.toml
// ---------------------------------------------------------------------------

export interface CalendarEvent extends ScheduleDefinition {
  title?: string;
}

const CALENDAR_TARGET_KEYS = ["session_id", "workspace", "model_id", "provider"] as const;

/** A schedule file without target fields: the target is always the employee's desk session. */
export function parseCalendarEvent(name: string, raw: string): ParseResult<CalendarEvent> {
  const t = tomlTable(raw);
  if (!t.ok) return t;
  for (const key of CALENDAR_TARGET_KEYS) {
    if (t.value[key] !== undefined) {
      return fail(
        `${key} is not allowed: a calendar event always goes to the employee's desk session`,
      );
    }
  }
  const title = t.value["title"];
  if (title !== undefined && typeof title !== "string") return fail("title must be a string");
  const parsed = parseScheduleFile(name, raw);
  if (!parsed.ok) return fail(parsed.error);
  return {
    ok: true,
    value: {
      ...parsed.def,
      ...(typeof title === "string" && title.trim() !== "" ? { title: title.trim() } : {}),
    },
  };
}

export function serializeCalendarEvent(fields: {
  title?: string;
  prompt: string;
  enabled: boolean;
  startAt: string;
  period?: string;
  endAt?: string;
}): string {
  const table: Record<string, unknown> = {
    ...(fields.title !== undefined ? { title: fields.title } : {}),
    prompt: fields.prompt,
    enabled: fields.enabled,
    start_at: fields.startAt,
    ...(fields.period !== undefined ? { period: fields.period } : {}),
    ...(fields.endAt !== undefined ? { end_at: fields.endAt } : {}),
  };
  return `${stringifyToml(table)}\n`;
}

// ---------------------------------------------------------------------------
// tickets/<yyyy-mm>/<column>/<yyyy-mm-dd>-<slug>.md
// ---------------------------------------------------------------------------

/** `<yyyy-mm-dd>-<slug>`; the slug is hyphen-joined lowercase English words, never a digit. */
export const TICKET_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z]+(?:-[a-z]+)*$/;

/** At most this many words in a derived slug, and at most this many characters in each. */
const SLUG_MAX_WORDS = 6;
const SLUG_MAX_WORD_LENGTH = 20;

/**
 * The slug of a ticket id, derived from a title or from a model's proposal: ASCII letters
 * only, lowercased, hyphen-joined. Digits are dropped — the id already starts with the date,
 * and `-2` on the end of a slug reads as a version rather than as a name. Text that carries
 * no Latin letters at all (a Chinese title) yields `""`, and one that yields a single word
 * says as little as none: both are the case the caller asks the model to name.
 */
export function slugify(text: string): string {
  return text
    .normalize("NFKD")
    .replace(/[̀-ͯ]/g, "")
    .toLowerCase()
    .replace(/[^a-z]+/g, " ")
    .trim()
    .split(/\s+/)
    .filter((w) => w !== "")
    .slice(0, SLUG_MAX_WORDS)
    .map((w) => w.slice(0, SLUG_MAX_WORD_LENGTH))
    .join("-");
}

const ALPHABET = "abcdefghijklmnopqrstuvwxyz";

/**
 * The letters that make a taken id unique: `2` → `b`, `3` → `c`, … `26` → `z`, `27` → `aa`.
 * Letters rather than numbers because the slug pattern has no digits in it, and starting at
 * `b` because the first candidate is the bare slug.
 */
export function slugSuffix(n: number): string {
  let out = "";
  for (let v = n; v > 0; v = Math.floor((v - 1) / ALPHABET.length)) {
    out = `${ALPHABET[(v - 1) % ALPHABET.length]}${out}`;
  }
  return out;
}

export interface TicketDoc {
  title: string;
  status: OrgTicketStatus;
  /** The ONE responsible principal (`agent:<id>` / `user:<id>`); every ticket has one. */
  owner: string;
  parent?: string;
  notify: string[];
  priority: OrgTicketPriority;
  due?: string;
  blocked?: string;
  blockedBy?: string;
  /** Contributing session ids, in the order they were attached (fact, server-written). */
  sessions: string[];
  /** The operation log, oldest first (fact, server-written). */
  history: OrgTicketHistoryEntry[];
  goal: string;
  acceptanceCriteria: string;
  /** Plain progress sentences, without their bullet; who wrote one and when is in the history. */
  progress: string[];
  result: string;
  /** Frontmatter keys this parser does not know, kept verbatim across a round trip. */
  extra: Record<string, unknown>;
  /** Sections beyond the four fixed ones, kept verbatim. */
  extraSections: Array<{ heading: string; body: string }>;
}

const SECTION_KEYS: Record<string, "goal" | "acceptanceCriteria" | "progress" | "result"> = {
  goal: "goal",
  "acceptance criteria": "acceptanceCriteria",
  progress: "progress",
  result: "result",
};

const KNOWN_FIELDS = new Set([
  "title",
  "status",
  "owner",
  "parent",
  "notify",
  "priority",
  "due",
  "blocked",
  "blocked_by",
  "sessions",
  "history",
]);

const HISTORY_ACTIONS: readonly OrgTicketHistoryAction[] = [
  "created",
  "assigned",
  "moved",
  "blocked",
  "unblocked",
  "progress",
  "session_started",
  "session_attached",
  "edited",
];

/** How much of a progress sentence the history entry that records it carries. */
export const HISTORY_NOTE_MAX = 80;

function isPersonPrincipal(raw: string): boolean {
  const p = parsePrincipal(raw);
  return p !== null && (p.kind === "agent" || p.kind === "user");
}

type Frontmatter =
  { kind: "none" } | { kind: "unterminated" } | { kind: "ok"; yaml: string; body: string };

/** The `---` fenced block at the top of the file, and everything after it. */
function splitFrontmatter(text: string): Frontmatter {
  const lines = text.split("\n");
  let i = 0;
  while (i < lines.length && lines[i]!.trim() === "") i++;
  if (lines[i]?.trim() !== "---") return { kind: "none" };
  const start = i + 1;
  for (let j = start; j < lines.length; j++) {
    if (lines[j]!.trim() === "---") {
      return {
        kind: "ok",
        yaml: lines.slice(start, j).join("\n"),
        body: lines.slice(j + 1).join("\n"),
      };
    }
  }
  return { kind: "unterminated" };
}

/**
 * A ticket file: YAML frontmatter followed by the prose sections. The frontmatter carries
 * the fields (the title among them — there is no H1), the prose carries `## Goal`,
 * `## Acceptance criteria`, `## Progress` and `## Result`; unknown fields and unknown
 * sections survive a round trip. A file that does not open with the frontmatter is not a
 * ticket.
 */
export function parseTicket(raw: string): ParseResult<TicketDoc> {
  const text = raw.replace(/\r\n/g, "\n");
  const fm = splitFrontmatter(text);
  if (fm.kind === "none") return fail("the file must start with `---` (YAML frontmatter)");
  if (fm.kind === "unterminated") return fail("the frontmatter block is not closed by `---`");
  let parsed: unknown;
  try {
    parsed = parseYaml(fm.yaml);
  } catch (err) {
    return fail(
      `Failed to parse the frontmatter: ${err instanceof Error ? err.message : String(err)}`,
    );
  }
  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
    return fail("the frontmatter is not a YAML mapping");
  }
  const front = parsed as Record<string, unknown>;
  const fields = ticketFields(front);
  if (!fields.ok) return fields;
  const sections = ticketSections(fm.body);
  if (!sections.ok) return sections;
  return { ok: true, value: { ...fields.value, ...sections.value } };
}

type TicketFields = Omit<
  TicketDoc,
  "goal" | "acceptanceCriteria" | "progress" | "result" | "extraSections"
>;

/** The frontmatter's fields, validated; anything this parser does not know lands in `extra`. */
function ticketFields(front: Record<string, unknown>): ParseResult<TicketFields> {
  const str = (key: string): string => {
    const v = front[key];
    return typeof v === "string" ? v.trim() : "";
  };
  const title = str("title");
  if (title === "") return fail("title must be a non-empty string");
  const status = str("status");
  if (!isTicketColumn(status)) {
    return fail(`status must be one of the board columns, got \`${status}\``);
  }
  const owner = str("owner");
  if (!isPersonPrincipal(owner)) return fail("owner must be agent:<id> or user:<id>");
  const parent = str("parent");
  if (parent !== "" && !TICKET_ID_PATTERN.test(parent)) return fail("parent must be a ticket id");
  const notifyList = front["notify"];
  if (notifyList !== undefined && notifyList !== null && !Array.isArray(notifyList)) {
    return fail("notify must be a list of principals");
  }
  // No `notify`, or an empty one: tell the owner when it is an employee — its next sweep
  // lists the change — and nobody when a person owns it, because one @-mention per closed
  // ticket is a badge nobody asked for. A person lists itself to be told.
  const notify =
    Array.isArray(notifyList) && notifyList.length > 0
      ? notifyList.map((n) => String(n).trim())
      : defaultTicketNotify(owner);
  for (const n of notify)
    if (!isPersonPrincipal(n)) return fail(`notify entry is not a principal: ${n}`);
  const priority = str("priority") === "" ? "P2" : str("priority");
  if (priority !== "P0" && priority !== "P1" && priority !== "P2") {
    return fail("priority must be P0, P1 or P2");
  }
  const due = str("due");
  if (due !== "" && !/^\d{4}-\d{2}-\d{2}/.test(due)) return fail("due must start with yyyy-mm-dd");
  const blocked = str("blocked");
  const blockedBy = str("blocked_by");
  if (blockedBy !== "" && !TICKET_ID_PATTERN.test(blockedBy) && !isPersonPrincipal(blockedBy)) {
    return fail("blocked_by must be a ticket id or a principal");
  }
  const sessionList = front["sessions"];
  if (sessionList !== undefined && sessionList !== null && !Array.isArray(sessionList)) {
    return fail("sessions must be a list of session ids");
  }
  const sessions = Array.isArray(sessionList) ? sessionList.map((s) => String(s).trim()) : [];
  const history = parseTicketHistory(front["history"]);
  if (!history.ok) return history;
  const extra: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(front)) if (!KNOWN_FIELDS.has(key)) extra[key] = value;
  return {
    ok: true,
    value: {
      title,
      status,
      owner,
      ...(parent !== "" ? { parent } : {}),
      notify,
      priority,
      ...(due !== "" ? { due } : {}),
      ...(blocked !== "" ? { blocked } : {}),
      ...(blockedBy !== "" ? { blockedBy } : {}),
      sessions,
      history: history.value,
      extra,
    },
  };
}

/** The `notify` list a ticket falls back to: its owner when an employee owns it, nobody otherwise. */
export function defaultTicketNotify(owner: string): string[] {
  return parsePrincipal(owner)?.kind === "agent" ? [owner] : [];
}

function parseTicketHistory(value: unknown): ParseResult<OrgTicketHistoryEntry[]> {
  if (value === undefined || value === null) return { ok: true, value: [] };
  if (!Array.isArray(value)) return fail("history must be a list of entries");
  const out: OrgTicketHistoryEntry[] = [];
  for (const [i, item] of value.entries()) {
    if (item === null || typeof item !== "object" || Array.isArray(item)) {
      return fail(`history[${i}] is not a mapping`);
    }
    const e = item as Record<string, unknown>;
    const at = typeof e["at"] === "string" ? e["at"].trim() : "";
    const by = typeof e["by"] === "string" ? e["by"].trim() : "";
    const action = typeof e["action"] === "string" ? e["action"].trim() : "";
    if (!(HISTORY_ACTIONS as readonly string[]).includes(action)) {
      return fail(`history[${i}].action is not a known action: ${action}`);
    }
    const note = typeof e["note"] === "string" ? e["note"] : undefined;
    out.push({
      at,
      by,
      action: action as OrgTicketHistoryAction,
      ...(note !== undefined && note !== "" ? { note } : {}),
    });
  }
  return { ok: true, value: out };
}

type TicketProse = Pick<
  TicketDoc,
  "goal" | "acceptanceCriteria" | "progress" | "result" | "extraSections"
>;

/** The prose half: the four fixed sections, plus any others kept as written. */
function ticketSections(body: string): ParseResult<TicketProse> {
  const out: TicketProse = {
    goal: "",
    acceptanceCriteria: "",
    progress: [],
    result: "",
    extraSections: [],
  };
  const sections: Array<{ heading: string; body: string[] }> = [];
  let current: { heading: string; body: string[] } | null = null;
  for (const line of body.split("\n")) {
    const h = /^## (.+)$/.exec(line);
    if (h) {
      current = { heading: h[1]!.trim(), body: [] };
      sections.push(current);
    } else if (current) {
      current.body.push(line);
    } else if (line.trim() !== "") {
      return fail(`text before the first section heading: ${line}`);
    }
  }
  for (const s of sections) {
    const key = SECTION_KEYS[s.heading.toLowerCase()];
    const text = trimBlank(s.body).join("\n");
    if (key === "progress") {
      out.progress = trimBlank(s.body)
        .filter((l) => l.trim() !== "")
        .map((l) => l.trim().replace(/^[-*]\s+/, ""));
    } else if (key !== undefined) {
      out[key] = text;
    } else {
      out.extraSections.push({ heading: s.heading, body: text });
    }
  }
  return { ok: true, value: out };
}

function trimBlank(lines: string[]): string[] {
  let a = 0;
  let b = lines.length;
  while (a < b && lines[a]!.trim() === "") a++;
  while (b > a && lines[b - 1]!.trim() === "") b--;
  return lines.slice(a, b);
}

export function serializeTicket(doc: TicketDoc): string {
  const front: Record<string, unknown> = {
    title: doc.title,
    status: doc.status,
    owner: doc.owner,
    ...(doc.parent !== undefined ? { parent: doc.parent } : {}),
    notify: doc.notify,
    priority: doc.priority,
    ...(doc.due !== undefined ? { due: doc.due } : {}),
    ...(doc.blocked !== undefined && doc.blocked !== "" ? { blocked: doc.blocked } : {}),
    ...(doc.blockedBy !== undefined && doc.blockedBy !== "" ? { blocked_by: doc.blockedBy } : {}),
    sessions: doc.sessions,
    history: doc.history.map((h) => ({
      at: h.at,
      by: h.by,
      action: h.action,
      ...(h.note !== undefined && h.note !== "" ? { note: h.note } : {}),
    })),
    ...doc.extra,
  };
  const yamlDoc = new YamlDocument(front);
  // One line per list and per history entry: a ticket file is read and hand-edited, and a
  // twenty-line `sessions` block would bury the fields above it.
  for (const key of ["notify", "sessions"]) {
    const node = yamlDoc.get(key, true);
    if (isSeq(node)) node.flow = true;
  }
  const history = yamlDoc.get("history", true);
  if (isSeq(history)) for (const item of history.items) if (isMap(item)) item.flow = true;
  const sections: string[] = [
    `## Goal\n${doc.goal}`,
    `## Acceptance criteria\n${doc.acceptanceCriteria}`,
    `## Progress\n${doc.progress.map((p) => `- ${p}`).join("\n")}`,
    `## Result\n${doc.result}`,
    ...doc.extraSections.map((s) => `## ${s.heading}\n${s.body}`),
  ];
  const yaml = yamlDoc.toString({ lineWidth: 0, flowCollectionPadding: false });
  return `---\n${yaml}---\n\n${sections.map((s) => s.trimEnd()).join("\n\n")}\n`;
}

/** One progress sentence as the history records it: the first {@link HISTORY_NOTE_MAX} characters, on one line. */
export function historyNote(text: string): string {
  return text
    .replace(/\s*\n\s*/g, " ")
    .trim()
    .slice(0, HISTORY_NOTE_MAX);
}

// ---------------------------------------------------------------------------
// channels/<channel_id>/channel.toml
// ---------------------------------------------------------------------------

/**
 * A channel's intent file. `everyone` and `members` are the two shapes of membership
 * and exactly one of them applies: the all-hands channel is `everyone = true` (every
 * employee and every Project member, no list to keep), every other channel carries the
 * explicit list its members edit through the API.
 */
export interface ChannelConfig {
  name: string;
  purpose: string;
  /** `user:<id>` / `agent:<id>` / `system` (the all-hands channel, created with the organization). */
  createdBy: string;
  /** ISO 8601 UTC. */
  createdAt: string;
  /** An archived channel is read-only: no posts, no invitations, no membership changes. */
  archived: boolean;
  /** Explicit membership; absent on the all-hands channel. */
  members?: string[];
  /** True only on the all-hands channel: membership is implicit and there is no list. */
  everyone?: boolean;
}

/**
 * Parses a channel file. The channel id decides which membership shape is legal, so it is
 * an argument rather than a field: `everyone` belongs to the all-hands channel and to no
 * other, and every other channel must list its members.
 */
export function parseChannelConfig(channelId: string, raw: string): ParseResult<ChannelConfig> {
  const t = tomlTable(raw);
  if (!t.ok) return t;
  const table = t.value;
  const name = table["name"];
  if (typeof name !== "string" || name.trim() === "")
    return fail("name must be a non-empty string");
  const purpose = table["purpose"] ?? "";
  if (typeof purpose !== "string") return fail("purpose must be a string");
  const createdBy = table["created_by"];
  if (typeof createdBy !== "string" || (createdBy !== "system" && !isPersonPrincipal(createdBy))) {
    return fail("created_by must be agent:<id>, user:<id> or system");
  }
  const createdAtRaw = table["created_at"];
  const createdAt =
    createdAtRaw instanceof Date
      ? createdAtRaw.toISOString()
      : typeof createdAtRaw === "string"
        ? createdAtRaw
        : null;
  if (createdAt === null || Number.isNaN(Date.parse(createdAt)))
    return fail("created_at must be an instant");
  const archived = table["archived"] ?? false;
  if (typeof archived !== "boolean") return fail("archived must be a boolean");
  const everyone = table["everyone"] ?? false;
  if (typeof everyone !== "boolean") return fail("everyone must be a boolean");
  if (everyone !== (channelId === DEFAULT_CHANNEL_ID)) {
    return fail(
      everyone
        ? `everyone belongs to the all-hands channel ${DEFAULT_CHANNEL_ID} and to no other`
        : `the all-hands channel ${DEFAULT_CHANNEL_ID} must be everyone = true`,
    );
  }
  const rawMembers = table["members"];
  if (everyone) {
    if (rawMembers !== undefined) return fail("an everyone channel keeps no members list");
    return {
      ok: true,
      value: {
        name: name.trim(),
        purpose: purpose.trim(),
        createdBy,
        createdAt: new Date(createdAt).toISOString(),
        archived,
        everyone: true,
      },
    };
  }
  if (!Array.isArray(rawMembers)) return fail("members must be a list of principals");
  const members: string[] = [];
  for (const m of rawMembers) {
    if (typeof m !== "string" || !isPersonPrincipal(m))
      return fail(`members entry is not a principal: ${String(m)}`);
    if (members.includes(m)) return fail(`duplicate member: ${m}`);
    members.push(m);
  }
  return {
    ok: true,
    value: {
      name: name.trim(),
      purpose: purpose.trim(),
      createdBy,
      createdAt: new Date(createdAt).toISOString(),
      archived,
      members,
    },
  };
}

export function serializeChannelConfig(cfg: ChannelConfig): string {
  const table = {
    name: cfg.name,
    purpose: cfg.purpose,
    created_by: cfg.createdBy,
    created_at: cfg.createdAt,
    archived: cfg.archived,
    ...(cfg.everyone === true ? { everyone: true } : { members: cfg.members ?? [] }),
  };
  return [
    "# channel.toml — a channel (the id is the directory name under channels/).",
    "# members: agent:<id> / user:<id>; only members read and post, and only a member's",
    "# mention reaches a desk. everyone = true marks the all-hands channel instead: every",
    "# employee and every Project member belongs to it and there is no list to keep.",
    "# archived: read-only, folded away in the UI, until a person unarchives it.",
    stringifyToml(table),
    "",
  ].join("\n");
}

// ---------------------------------------------------------------------------
// channels/<channel_id>/<yyyy-mm-dd>.jsonl
// ---------------------------------------------------------------------------

export const CHANNEL_MESSAGE_ID_PATTERN = /^msg-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{8}$/;

export function parseChannelMessageLine(line: string): ParseResult<OrgChannelMessage> {
  let v: unknown;
  try {
    v = JSON.parse(line);
  } catch {
    return fail("line is not JSON");
  }
  if (v === null || typeof v !== "object") return fail("line is not a JSON object");
  const o = v as Record<string, unknown>;
  if (typeof o["id"] !== "string" || !CHANNEL_MESSAGE_ID_PATTERN.test(o["id"]))
    return fail("id is not a message id");
  if (typeof o["time"] !== "string" || Number.isNaN(Date.parse(o["time"])))
    return fail("time is not an instant");
  if (typeof o["sender"] !== "string" || parsePrincipal(o["sender"]) === null)
    return fail("sender is not a principal");
  const hop = o["hop"];
  if (typeof hop !== "number" || !Number.isInteger(hop) || hop < 0)
    return fail("hop must be a non-negative integer");
  if (typeof o["text"] !== "string") return fail("text must be a string");
  const mentions = o["mentions"] ?? [];
  if (
    !Array.isArray(mentions) ||
    mentions.some((m) => typeof m !== "string" || parsePrincipal(m) === null)
  ) {
    return fail("mentions must be a list of principals");
  }
  let refs: OrgChannelMessage["refs"];
  if (o["refs"] !== undefined) {
    const r = o["refs"];
    if (r === null || typeof r !== "object") return fail("refs must be an object");
    const rr = r as Record<string, unknown>;
    refs = {
      ...(typeof rr["ticket"] === "string" ? { ticket: rr["ticket"] } : {}),
      ...(typeof rr["session"] === "string" ? { session: rr["session"] } : {}),
      ...(typeof rr["reply_to"] === "string" ? { replyTo: rr["reply_to"] } : {}),
    };
  }
  // The kind is taken as written rather than checked against the known list: a line a newer
  // server wrote still parses here, and a client that does not know the kind shows `text`.
  let notice: OrgChannelMessage["notice"];
  if (o["notice"] !== undefined) {
    const n = o["notice"];
    if (n === null || typeof n !== "object") return fail("notice must be an object");
    const nn = n as Record<string, unknown>;
    if (typeof nn["kind"] !== "string" || nn["kind"] === "")
      return fail("notice.kind must be a non-empty string");
    const params = nn["params"] ?? {};
    if (params === null || typeof params !== "object" || Array.isArray(params))
      return fail("notice.params must be an object");
    const entries = Object.entries(params as Record<string, unknown>);
    if (entries.some(([, value]) => typeof value !== "string"))
      return fail("notice.params values must be strings");
    notice = {
      kind: nn["kind"] as OrgChannelNoticeKind,
      params: Object.fromEntries(entries) as Record<string, string>,
    };
  }
  return {
    ok: true,
    value: {
      id: o["id"],
      time: o["time"],
      sender: o["sender"],
      hop,
      text: o["text"],
      mentions: mentions as string[],
      ...(refs !== undefined && Object.keys(refs).length > 0 ? { refs } : {}),
      ...(notice !== undefined ? { notice } : {}),
    },
  };
}

export function serializeChannelMessageLine(msg: OrgChannelMessage): string {
  const refs =
    msg.refs === undefined
      ? undefined
      : {
          ...(msg.refs.ticket !== undefined ? { ticket: msg.refs.ticket } : {}),
          ...(msg.refs.session !== undefined ? { session: msg.refs.session } : {}),
          ...(msg.refs.replyTo !== undefined ? { reply_to: msg.refs.replyTo } : {}),
        };
  return JSON.stringify({
    id: msg.id,
    time: msg.time,
    sender: msg.sender,
    hop: msg.hop,
    text: msg.text,
    mentions: msg.mentions,
    ...(refs !== undefined && Object.keys(refs).length > 0 ? { refs } : {}),
    ...(msg.notice !== undefined ? { notice: msg.notice } : {}),
  });
}

export interface MentionToken {
  /** `agent` / `user` when the writer disambiguated, absent for the short form. */
  prefix?: "agent" | "user";
  /** The bare id, or `all`. */
  id: string;
}

/** The `@` tokens in a message: `@id`, `@agent:id`, `@user:id`, `@all`; who they resolve to is the service's call. */
export function extractMentionTokens(text: string): MentionToken[] {
  const out: MentionToken[] = [];
  const re = /(^|[^A-Za-z0-9_@])@(?:(agent|user):)?([A-Za-z0-9][A-Za-z0-9_.-]*)/g;
  for (const m of text.matchAll(re)) {
    const prefix = m[2] as "agent" | "user" | undefined;
    const id = m[3]!.replace(/[.-]+$/, "");
    if (id === "") continue;
    out.push({ ...(prefix !== undefined ? { prefix } : {}), id });
  }
  return out;
}