Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
19.5 KB
Raw Blame
/**
 * The topic actions behind the `brain_topic` MCP tool and the `o2b topic`
 * verbs (design D9; spec `topics` "Topics on request"; task 3.5): one
 * implementation, so the tool and the CLI cannot disagree.
 *
 * Reads (`list`, `show`, `review`) answer at the caller's reach: below
 * local reach only shared topics exist (`read.ts`), and a write that names
 * a topic the caller cannot see is refused exactly as one that names no
 * topic, so neither a private topic's content nor its existence crosses.
 *
 * Writes are topic records (`write.ts`). The requested actions (create,
 * rename, status, goal, assign, unassign, merge, split, link, archive,
 * undo) carry `human` authority when the user runs them (`o2b topic`) and
 * `agent` authority through `brain_topic` (design D9, D18). `record` adds
 * an agent's own decision, open question, log entry, milestone,
 * resolution or completion, with `agent` authority by default. Every
 * default can be named instead with `authority` (`human` is refused
 * below local reach).
 */

import type { AppendResult } from "../store/appender.ts";
import type { Authority } from "../store/constants.ts";
import { SETTING_VIEW_LANGUAGE } from "../store/constants.ts";
import { sharedSetting } from "./settings.ts";
import { DELIVERY_TREATMENT, shapeStoredTextForDelivery } from "../brain/delivery-shaping.ts";
import { viewStrings } from "../view/i18n.ts";
import { topicPages } from "../view/topic-pages.ts";
import {
  TOPIC_ASSIGN_KIND,
  TOPIC_GOAL_KIND,
  TOPIC_LINK_KIND,
  TOPIC_MERGE_KIND,
  TOPIC_PERSONAL_SCOPE,
  TOPIC_RENAME_KIND,
  TOPIC_SPLIT_KIND,
  TOPIC_STATUS_KIND,
  TOPIC_UNASSIGN_KIND,
  TOPIC_UNDO_KIND,
  type TopicRecordKind,
} from "./constants.ts";
import type { TopicFold, TopicState } from "./fold.ts";
import { reviewTopics } from "./plan.ts";
import { readTopics, type TopicRead } from "./read.ts";
import { createTopicEvent, writeTopicEvents, type TopicEvent } from "./write.ts";
import { privateWithheld } from "../store/caller-reach.ts";
import { SETTING_TOPIC_QUIET_DAYS } from "../store/constants.ts";

export const TOPIC_ACTIONS = Object.freeze([
  "list",
  "show",
  "review",
  "create",
  "rename",
  "status",
  "goal",
  "assign",
  "unassign",
  "merge",
  "split",
  "link",
  "archive",
  "undo",
  "record",
] as const);
export type TopicAction = (typeof TOPIC_ACTIONS)[number];

/** The kinds `record` writes. */
export const TOPIC_RECORD_ACTION_KINDS = Object.freeze([
  "decision",
  "open-question",
  "log-entry",
  "milestone",
  "question-resolved",
  "milestone-done",
] as const);

/** A topic action refused before anything was read or written. */
export class TopicActionError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "TopicActionError";
  }
}

export interface TopicActionInput {
  readonly action: string;
  readonly topic?: string;
  readonly title?: string;
  readonly description?: string | null;
  readonly goal?: string | null;
  readonly scope?: string;
  readonly status?: string;
  readonly resolved?: string;
  readonly record?: string;
  readonly into?: string;
  readonly to?: string;
  readonly items?: ReadonlyArray<string>;
  readonly records?: ReadonlyArray<string>;
  readonly removed?: boolean;
  readonly private?: boolean;
  readonly authority?: string;
  /** `record`: the kind and its fields. */
  readonly kind?: string;
  /** `record`: the topic that owns the named item, when merged topics share its id. */
  readonly owner?: string;
  readonly fields?: Readonly<Record<string, unknown>>;
  /** `list`: the scope to list (default: every topic). */
  readonly listScope?: string;
}

export interface TopicActionContext {
  readonly configPath?: string;
  readonly agent?: string;
  readonly now?: () => number;
  /**
   * The user is the caller (the `o2b topic` CLI): the requested actions
   * default to `human` authority. Every other caller (an agent through
   * `brain_topic`) defaults to `agent` and must name `human` to claim it.
   */
  readonly humanRequest?: boolean;
}

function need(input: TopicActionInput, field: keyof TopicActionInput): string {
  const value = input[field];
  if (typeof value !== "string" || value.trim() === "") {
    throw new TopicActionError(`${input.action}: '${field}' is required`);
  }
  return value.trim();
}

function authorityOf(input: TopicActionInput, fallback: Authority): Authority {
  if (input.authority === undefined) return fallback;
  if (input.authority !== "human" && input.authority !== "agent") {
    throw new TopicActionError("authority must be human or agent");
  }
  // A caller below local reach (a remote MCP transport) is never taken to
  // speak for the user: its records would outweigh the user's own.
  if (input.authority === "human" && privateWithheld()) {
    throw new TopicActionError("human authority is refused below local reach");
  }
  return input.authority;
}

/** The fields `record` accepts for each kind; any other field is refused. */
const RECORD_FIELDS: Readonly<Record<string, ReadonlyArray<string>>> = Object.freeze({
  decision: ["item", "text", "serves", "removed"],
  "open-question": ["item", "text", "removed"],
  "log-entry": ["item", "text", "class", "reason", "removed"],
  milestone: ["item", "text", "removed"],
  "question-resolved": ["question", "answer"],
  "milestone-done": ["milestone", "evidence"],
});

/** The field of a completion that names its item, and the item's kind. */
const NAMED_ITEM: Readonly<Record<string, { field: string; kind: string }>> = Object.freeze({
  "question-resolved": { field: "question", kind: "open-question" },
  "milestone-done": { field: "milestone", kind: "milestone" },
});

/**
 * The topic a `record` event is written under, after its item reference
 * is checked against the caller's fold: an item named by a completion, or
 * by an edit, must be an item of that topic of the right kind (a merged
 * topic's item is written under the topic that owns it). Below local reach
 * a record may not pick a new item id: the item would collide with one of
 * a private record the caller cannot see. Every miss gives one message,
 * so a hidden item and an absent one answer alike.
 */
function recordTopic(
  fold: TopicFold,
  topic: TopicState,
  kind: string,
  fields: Readonly<Record<string, unknown>>,
  owner: string | undefined,
): string {
  for (const key of Object.keys(fields)) {
    if (!(RECORD_FIELDS[kind] ?? []).includes(key)) {
      throw new TopicActionError(`record: ${kind} takes no field '${key}'`);
    }
  }
  const named = NAMED_ITEM[kind];
  const field = named?.field ?? "item";
  const want = named?.kind ?? kind;
  const id = fields[field];
  // `owner` names this topic or one merged into it; any other id (a typo,
  // an unrelated topic, one the caller cannot see) is refused alike, with
  // or without an item id.
  if (owner !== undefined && owner !== topic.id && fold.canonical(owner) !== topic.id) {
    throw new TopicActionError(
      `record: owner ${owner} is not this topic or a topic merged into it (${topic.id})`,
    );
  }
  if (id === undefined && named === undefined) return topic.id;
  if (typeof id !== "string") throw new TopicActionError(`record: ${kind} needs '${field}'`);
  // After a merge two owners can hold the same item id: `owner` says which.
  const matches = topic.items.filter(
    (i) => i.id === id && (owner === undefined || i.owner === owner),
  );
  if (matches.length > 1) {
    throw new TopicActionError(
      `record: item ${id} is on more than one merged topic; name its owner (${matches.map((i) => i.owner).join(", ")})`,
    );
  }
  const item = matches[0];
  if (item !== undefined && item.kind === want) return item.owner;
  // A new item is never picked with `owner`: an owner names an item that exists.
  if (item === undefined && named === undefined && owner === undefined && !privateWithheld()) {
    // An id the topic once held still names that item after a split moved it.
    if (fold.movedAway(topic.id, id)) {
      throw new TopicActionError(
        `record: item ${id} of topic ${topic.id} moved to another topic; pick another id`,
      );
    }
    return topic.id;
  }
  throw new TopicActionError(`record: no ${want} item ${id} on topic ${topic.id}`);
}

/**
 * The `split` records of a request. Each item listed must be one the
 * topic shows, and it moves by a split written under the topic that owns
 * it: an item of a topic merged into this one is that topic's own, which
 * a split of this topic would not find. An id two merged owners share
 * needs `owner`.
 */
function splitEvents(
  fold: TopicFold,
  topic: TopicState,
  input: TopicActionInput,
  into: string,
  event: (topic: string, body: Record<string, unknown>) => TopicEvent,
): TopicEvent[] {
  const owner = input.owner;
  if (owner !== undefined && owner !== topic.id && fold.canonical(owner) !== topic.id) {
    throw new TopicActionError(
      `split: owner ${owner} is not this topic or a topic merged into it (${topic.id})`,
    );
  }
  const byOwner = new Map<string, string[]>([[topic.id, []]]);
  for (const id of input.items ?? []) {
    const matches = topic.items.filter(
      (i) => i.id === id && (owner === undefined || i.owner === owner),
    );
    if (matches.length > 1) {
      throw new TopicActionError(
        `split: item ${id} is on more than one merged topic; name its owner (${matches.map((i) => i.owner).join(", ")})`,
      );
    }
    if (matches[0] === undefined) {
      throw new TopicActionError(`split: no item ${id} on topic ${topic.id}`);
    }
    byOwner.set(matches[0].owner, [...(byOwner.get(matches[0].owner) ?? []), id]);
  }
  const records = input.records !== undefined ? { records: input.records } : {};
  const own = byOwner.get(topic.id)!;
  // The named topic's split comes first and carries the records; a merged
  // owner's split carries only its items.
  return [
    ...(own.length > 0 || input.records !== undefined || byOwner.size === 1
      ? [
          event(topic.id, {
            into,
            // A merged owner's items go in its own split; an empty list is invalid.
            ...(own.length > 0 ? { items: own } : {}),
            ...records,
          }),
        ]
      : []),
    ...[...byOwner]
      .filter(([id]) => id !== topic.id)
      .map(([id, items]) => event(id, { into, items })),
  ];
}

/** The fence origin of topic text below local reach. */
const TOPIC_TEXT_ORIGIN = "stored text: agent-authored (topic records)";

/**
 * Topic text as the caller of the work running now may be handed it:
 * agent-written, so fenced below local reach as every other stored text an
 * agent wrote; as is for a local caller.
 */
function delivered<T extends string | null>(text: T): T {
  if (text === null || !privateWithheld()) return text;
  return shapeStoredTextForDelivery(text, {
    treatment: DELIVERY_TREATMENT.fenced,
    origin: TOPIC_TEXT_ORIGIN,
  }).text as T;
}

/** A topic head: what an agent gets for a topic without its body. */
export function topicHead(topic: TopicState): Record<string, unknown> {
  return {
    id: topic.id,
    title: delivered(topic.title),
    description: delivered(topic.description),
    status: topic.status,
    ...(topic.resolved !== null ? { resolved: topic.resolved } : {}),
    goal: delivered(topic.goal),
    scope: delivered(topic.scope),
    created_at: new Date(topic.createdAt).toISOString(),
    updated_at: new Date(topic.updatedAt).toISOString(),
  };
}

function topicDetail(topic: TopicState): Record<string, unknown> {
  return {
    ...topicHead(topic),
    links: topic.links,
    goal_proposals: topic.goalProposals.map((p) => ({
      agent: p.agent,
      goal: delivered(p.goal),
      record: p.record,
    })),
    items: topic.items.map((i) => ({
      id: i.id,
      owner: i.owner,
      kind: i.kind,
      text: delivered(i.text),
      ...(i.logClass !== undefined ? { class: i.logClass } : {}),
      ...(i.reason !== undefined ? { reason: delivered(i.reason) } : {}),
      ...(i.serves !== undefined ? { serves: i.serves } : {}),
      authority: i.author.authority,
      agent: i.author.agent,
      created_at: new Date(i.createdAt).toISOString(),
      ...(i.done !== undefined ? { done: new Date(i.done.at).toISOString() } : {}),
      ...(i.doneProposed !== undefined ? { looks_done: true } : {}),
      ...(i.resolved !== undefined ? { resolved: new Date(i.resolved.at).toISOString() } : {}),
    })),
  };
}

/** The topic `id` names after merges, if the caller can see it. */
function visibleTopic(read: TopicRead, id: string): TopicState {
  const canonical = read.fold.canonical(id);
  const topic = canonical === null ? undefined : read.fold.topics.get(canonical);
  if (topic === undefined) throw new TopicActionError(`no topic with id ${id}`);
  return topic;
}

function shownMarkdown(read: TopicRead, topic: TopicState, configPath?: string): string {
  const lang = sharedSetting(SETTING_VIEW_LANGUAGE, configPath);
  const strings = viewStrings(typeof lang === "string" ? lang : null);
  // A local caller sees its private topics too; below local reach the
  // fold already holds none.
  const pages = topicPages(read.storeId ?? "", read.fold, strings, {
    includePrivate: !privateWithheld(),
  });
  const page = pages.find((p) => p.topic === topic.id && p.page.endsWith("/topic.md"));
  const text = page === undefined ? "" : `${page.lines.map((l) => l.text).join("\n")}\n`;
  // Topic text is written by agents: below local reach it is delivered
  // fenced, as every other stored text that agents wrote.
  if (!privateWithheld()) return text;
  return shapeStoredTextForDelivery(text, {
    treatment: DELIVERY_TREATMENT.fenced,
    origin: TOPIC_TEXT_ORIGIN,
  }).text;
}

function quietDays(configPath?: string): number {
  return sharedSetting(SETTING_TOPIC_QUIET_DAYS, configPath) as number;
}

function listJson(fold: TopicFold, scope: string | undefined): Record<string, unknown>[] {
  return [...fold.topics.values()]
    .filter((t) => t.mergedInto === null && (scope === undefined || t.scope === scope))
    .toSorted((a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : 1))
    .map(topicHead);
}

/** The events of a write action, against what the caller can see. */
function eventsOf(
  input: TopicActionInput,
  read: TopicRead,
  now: number,
  humanRequest: boolean,
): TopicEvent[] {
  const human = authorityOf(input, humanRequest ? "human" : "agent");
  const event = (
    kind: TopicRecordKind,
    topic: string,
    body: Record<string, unknown>,
  ): TopicEvent => ({
    kind,
    topic,
    authority: human,
    body,
  });
  const topicId = (): string => visibleTopic(read, need(input, "topic")).id;
  switch (input.action) {
    case "create":
      return [
        createTopicEvent({
          title: need(input, "title"),
          scope: input.scope ?? TOPIC_PERSONAL_SCOPE,
          authority: human,
          ...(input.description !== undefined ? { description: input.description } : {}),
          ...(input.goal !== undefined ? { goal: input.goal } : {}),
          now,
        }),
      ];
    case "rename":
      return [
        event(TOPIC_RENAME_KIND, topicId(), {
          ...(input.title !== undefined ? { title: input.title } : {}),
          ...(input.description !== undefined ? { description: input.description } : {}),
        }),
      ];
    case "status":
      return [
        event(TOPIC_STATUS_KIND, topicId(), {
          status: need(input, "status"),
          ...(input.resolved !== undefined ? { resolved: input.resolved } : {}),
        }),
      ];
    case "archive":
      return [event(TOPIC_STATUS_KIND, topicId(), { status: "closed" })];
    case "goal":
      return [event(TOPIC_GOAL_KIND, topicId(), { goal: input.goal ?? null })];
    case "assign":
      return [event(TOPIC_ASSIGN_KIND, topicId(), { record: need(input, "record") })];
    case "unassign":
      return [event(TOPIC_UNASSIGN_KIND, topicId(), { record: need(input, "record") })];
    case "merge": {
      const into = visibleTopic(read, need(input, "into")).id;
      return [event(TOPIC_MERGE_KIND, topicId(), { into })];
    }
    case "split": {
      const into = visibleTopic(read, need(input, "into")).id;
      const topic = visibleTopic(read, need(input, "topic"));
      return splitEvents(read.fold, topic, input, into, (t, body) =>
        event(TOPIC_SPLIT_KIND, t, body),
      );
    }
    case "link": {
      const to = visibleTopic(read, need(input, "to")).id;
      return [
        event(TOPIC_LINK_KIND, topicId(), {
          to,
          ...(input.removed === true ? { removed: true } : {}),
        }),
      ];
    }
    case "undo": {
      const record = need(input, "record");
      const topic = read.recordTopics.get(record);
      // An undo names a topic record the caller can see; any other id is
      // "no such record". Its topic may be gone (an undone create): undoing
      // that undo brings the topic back.
      if (topic === undefined) {
        throw new TopicActionError(`no topic record with id ${record}`);
      }
      return [event(TOPIC_UNDO_KIND, topic, { record })];
    }
    case "record": {
      const kind = need(input, "kind");
      if (!(TOPIC_RECORD_ACTION_KINDS as ReadonlyArray<string>).includes(kind)) {
        throw new TopicActionError(
          `record: kind must be one of ${TOPIC_RECORD_ACTION_KINDS.join(", ")}`,
        );
      }
      const fields = input.fields ?? {};
      return [
        {
          kind: kind as TopicRecordKind,
          topic: recordTopic(
            read.fold,
            visibleTopic(read, need(input, "topic")),
            kind,
            fields,
            input.owner,
          ),
          authority: authorityOf(input, "agent"),
          body: { ...fields },
        },
      ];
    }
    default:
      throw new TopicActionError(`unknown action: ${input.action}`);
  }
}

/** Run one topic action and return its JSON answer. */
export function runTopicAction(
  input: TopicActionInput,
  context: TopicActionContext = {},
): Record<string, unknown> {
  if (!(TOPIC_ACTIONS as ReadonlyArray<string>).includes(input.action)) {
    throw new TopicActionError(`action must be one of ${TOPIC_ACTIONS.join(", ")}`);
  }
  const now = (context.now ?? Date.now)();
  const read = readTopics(context.configPath);
  switch (input.action) {
    case "list":
      return { action: "list", topics: listJson(read.fold, input.listScope) };
    case "show": {
      const topic = visibleTopic(read, need(input, "topic"));
      return {
        action: "show",
        topic: topicDetail(topic),
        page: shownMarkdown(read, topic, context.configPath),
      };
    }
    case "review": {
      // A fold over a partial read may miss topics: no proposal is made from it.
      if (read.unreadable.length > 0) {
        return {
          action: "review",
          incomplete: true,
          merges: [],
          quiet: [],
          ...(privateWithheld() ? {} : { unreadable: read.unreadable }),
        };
      }
      const review = reviewTopics(read.fold, now, quietDays(context.configPath));
      return {
        action: "review",
        merges: review.merges.map((m) => ({ topics: m.topics, score: m.score })),
        quiet: review.quiet,
      };
    }
  }
  const events = eventsOf(input, read, now, context.humanRequest === true);
  const written: AppendResult[] = writeTopicEvents(
    events.map((e) => (context.agent !== undefined ? { ...e, agent: context.agent } : e)),
    {
      ...(context.configPath !== undefined ? { configPath: context.configPath } : {}),
      ...(input.private !== undefined ? { private: input.private } : {}),
    },
  );
  return {
    action: input.action,
    // A split answers the topic it names, also when a merged owner's split comes first.
    topic:
      input.action === "split" ? visibleTopic(read, need(input, "topic")).id : events[0]!.topic,
    records: written.map((w) => w.record.id),
  };
}