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
21.2 KB
Raw Blame
/**
 * The record-item uses of the dream-time decide pass (design D10):
 * `event_kind` derives one item record per held record, and the
 * `question_resolved` and `milestone_done` proposals, built from the
 * fold and the deterministic plan the orchestrator (`decide.ts`) read.
 * One file per use family; the shared context lives in
 * `decide-shared.ts`, the writes happen under the planning lock
 * (`verdict-writes.ts`).
 */

import type { DecisionChoiceQuestion, DecisionNoulQuestion } from "../decision-model/contract.ts";
import { mayStartRequest } from "../decision-model/request-floor.ts";
import {
  EVENT_KIND_QUESTIONS,
  MILESTONE_DONE_QUESTIONS,
  QUESTION_RESOLVED_QUESTIONS,
  TOPIC_DECISION_LIMITS,
} from "../decision-model/questions-topics.ts";
import { mayShareRecord } from "../decision-model/egress-guard.ts";
import { runDecision } from "../decision-model/run.ts";
import { stripPrivateRegions } from "../redactor.ts";
import { appliedThreshold } from "../decision-model/use-thresholds.ts";
import { buildCandidateState, clip } from "../decision-model/state.ts";
import type { TopicCandidate } from "./candidates.ts";
import type { TopicFold } from "./fold.ts";
import {
  choiceConfidence,
  headFields,
  headIsPrivateInput,
  holderOf,
  itemIsPrivateInput,
  noulProbability,
  requestOptions,
  recordCandidate,
  WITHHELD_ID,
  type PassContext,
  requestTimeoutMs,
} from "./decide-shared.ts";
import { verdictBody } from "./verdicts.ts";

/**
 * The topic holding each candidate this pass: the fold's assignments,
 * else the route `topic_route` accepted earlier in this pass (a `none`
 * keeps the record free), else the deterministic plan's route.
 */
function holdingTopic(ctx: PassContext, candidate: TopicCandidate): string | null {
  const held = holderOf(ctx.fold, candidate);
  if (held !== null) return held;
  const accepted = ctx.out.routes.get(candidate.id);
  if (accepted !== undefined) return accepted.topic;
  const routed = ctx.plan.routes.find((route) => route.record === candidate.id);
  return routed?.topic ?? null;
}

/**
 * Whether the topic already carries the derived item of `recordId` (item
 * id = record id), or carried it until a split moved it away: the id
 * still names that item, so no second one is derived.
 */
function hasDerivedItem(fold: TopicFold, topicId: string, recordId: string): boolean {
  return (
    (fold.topics.get(topicId)?.items.some((item) => item.id === recordId) ?? false) ||
    fold.movedAway(topicId, recordId)
  );
}

/**
 * An item by its owner and id: item ids are a topic's own, and a merged
 * topic shows the items of the topics merged into it, so the id alone
 * can name two items.
 */
function ownedItemKey(item: { readonly owner: string; readonly id: string }): string {
  return `${item.owner}/${item.id}`;
}

/** The asked-set subject of a resolution question: the record and the questions offered. */
function resolutionSubject(
  recordId: string,
  questions: ReadonlyArray<{ readonly owner: string; readonly id: string }>,
): string {
  return `${recordId}:${questions.map(ownedItemKey).join(",")}`;
}

/** The asked-set subject of a milestone question: the milestone and its evidence. */
function completionSubject(
  milestone: { readonly owner: string; readonly id: string },
  members: ReadonlyArray<{ readonly id: string }>,
): string {
  return `${ownedItemKey(milestone)}:${members.map((m) => m.id).join(",")}`;
}

// ----- event_kind ------------------------------------------------------------

/**
 * `event_kind` (design D10): `choice` per candidate held by a topic
 * (assigned earlier or routed this pass) with no derived item yet,
 * batched one scope per request and at most `recordsPerRequest` records
 * per request, the state `{ records: { R0..: { topic, text } } }` with
 * the topic title. A non-routine answer at or above `kind_min` becomes a
 * kinds verdict; the derived item record is written under the planning
 * lock (`verdict-writes.ts`), the item id equal to the record id, which
 * makes the pass idempotent. Routine answers and every failure keep
 * today's behaviour (no page item).
 */
async function decideEventKinds(ctx: PassContext): Promise<void> {
  const use = "event_kind" as const;
  const entries: Array<{ candidate: TopicCandidate; topic: string }> = [];
  for (const candidate of ctx.candidates) {
    const topic = holdingTopic(ctx, candidate);
    if (topic === null) continue;
    if (hasDerivedItem(ctx.fold, topic, candidate.id)) continue;
    if (ctx.asked.has(use, candidate.id)) continue;
    // A record the egress rule keeps home is skipped before the cap.
    if (!mayShareRecord(ctx.cfg, use, candidate.private)) continue;
    entries.push({ candidate, topic });
  }
  if (entries.length > TOPIC_DECISION_LIMITS.recordsPerPass) {
    entries.length = TOPIC_DECISION_LIMITS.recordsPerPass;
  }
  for (let i = 0; i < entries.length; i += TOPIC_DECISION_LIMITS.recordsPerRequest) {
    if (!mayStartRequest(ctx.clock(), ctx.until, ctx.cfg.timeoutMs)) return;
    // Sequential by design: the budget is checked before every request.
    // oxlint-disable-next-line no-await-in-loop
    await runKindRequest(ctx, use, entries.slice(i, i + TOPIC_DECISION_LIMITS.recordsPerRequest));
  }
}

async function runKindRequest(
  ctx: PassContext,
  use: "event_kind",
  entries: ReadonlyArray<{ candidate: TopicCandidate; topic: string }>,
): Promise<void> {
  // Each masked record carries its holding topic's title beside its text,
  // inside the state the builder measures against `maxStateTokens`.
  const built = buildCandidateState({
    candidates: entries.map((entry) => ({
      ...recordCandidate(ctx, use, entry.candidate),
      fields: { topic: headFields(ctx, use, entry.topic)?.title ?? "" },
    })),
    prefix: EVENT_KIND_QUESTIONS.recordPrefix,
    clipChars: TOPIC_DECISION_LIMITS.recordClipChars,
    maxStateTokens: ctx.cfg.maxStateTokens,
    frame: (texts) => ({ records: texts }),
  });
  if (built.kind !== "ok") return;
  const state = built.state;
  const context = {
    /** `map[k]` is the entry behind mask `R<k>`. */
    map: new Map<number, (typeof entries)[number]>(),
  };
  built.included.forEach((candidateIndex, k) => context.map.set(k, entries[candidateIndex]!));
  const questions: Record<string, DecisionChoiceQuestion> = {};
  for (const [k] of context.map) {
    questions[EVENT_KIND_QUESTIONS.kindId(k)] = EVENT_KIND_QUESTIONS.kind(k);
  }
  const result = await runDecision<{ map: Map<number, (typeof entries)[number]> }>(
    use,
    () => ({
      kind: "ok",
      state,
      candidateCount: built.included.length,
      context,
    }),
    () => questions,
    {
      config: ctx.cfg,
      timeoutMs: requestTimeoutMs(ctx),
      ...requestOptions(ctx, (response, builtContext) => {
        const details: Record<string, unknown> = {
          record_ids: entries.map((entry) =>
            mayShareRecord(ctx.cfg, use, entry.candidate.private)
              ? entry.candidate.id
              : WITHHELD_ID,
          ),
        };
        if (response === null || builtContext === null) return details;
        const chosen: Array<string | null> = [];
        const probabilities: Array<number | null> = [];
        for (const [k] of (builtContext as { map: Map<number, (typeof entries)[number]> }).map) {
          const a = response.answers[EVENT_KIND_QUESTIONS.kindId(k)];
          const pick = a?.valid === true ? choiceConfidence(a) : null;
          chosen.push(pick?.key ?? null);
          probabilities.push(pick?.confidence ?? null);
        }
        details["chosen"] = chosen;
        details["probabilities"] = probabilities;
        return details;
      }),
    },
  );
  if (result.status !== "ok") return;
  const answered = { model: result.answeredBy.model, mode: result.mode };
  const kindMin = appliedThreshold(ctx.cfg, use, result.answeredBy.model, "kind_min");
  // Every answer reads the whole request: each record sent and the topic
  // title beside it (another record's too) is an input of every item.
  const requestPrivate = [...context.map.values()].some(
    (entry) => entry.candidate.private || headIsPrivateInput(ctx, use, entry.topic, ["title"]),
  );
  for (const [k, entry] of context.map) {
    const a = result.response.answers[EVENT_KIND_QUESTIONS.kindId(k)];
    if (a?.valid !== true) continue;
    const pick = choiceConfidence(a);
    // An answer that writes nothing (shadow, below the threshold, a
    // routine kind) is entered in the asked set: not asked again.
    if (
      result.mode !== "enforce" ||
      pick === null ||
      pick.confidence < kindMin ||
      pick.key === "routine"
    ) {
      ctx.asked.add(use, entry.candidate.id, answered, entry.candidate.at);
      continue;
    }
    ctx.out.kinds.set(entry.candidate.id, {
      kind: pick.key,
      topic: entry.topic,
      privateInput: requestPrivate,
      verdict: verdictBody(use, result.response, result.answeredBy.provider, pick.confidence),
    });
  }
}

// ----- question_resolved -----------------------------------------------------

/** The topic's open questions without a pending proposal, oldest first. */
function openQuestions(
  ctx: PassContext,
  use: "question_resolved",
  topicId: string,
): Array<{ id: string; owner: string; text: string; createdAt: number; privateInput: boolean }> {
  const topic = ctx.fold.topics.get(topicId);
  return (
    (topic?.items ?? [])
      .filter(
        (item) =>
          item.kind === "open-question" &&
          item.resolved === undefined &&
          item.resolveProposed === undefined &&
          // A private question (or one of a private topic) is no option
          // when its text may not leave the machine.
          mayShareRecord(ctx.cfg, use, item.private || topic!.private),
      )
      // Side texts: `<private>` regions are stripped, as from every candidate.
      .map((item) => ({
        id: item.id,
        owner: item.owner,
        text: stripPrivateRegions(item.text),
        createdAt: item.createdAt,
        privateInput: itemIsPrivateInput(ctx, use, item, topic!.private),
      }))
      .toSorted((a, b) => a.createdAt - b.createdAt)
  );
}

/**
 * `question_resolved` (design D10): `choice` per record held by a topic
 * that has open questions, the record newer than the question; the
 * options are that topic's open questions without a pending proposal
 * (capped, oldest first) plus `none`. A chosen question at or above
 * `resolved_min` becomes a resolution verdict; the `question-resolved`
 * proposal record is written under the planning lock, and the fold
 * shows it as "looks answered". Everything else proposes nothing.
 */
async function decideResolutions(ctx: PassContext): Promise<void> {
  const use = "question_resolved" as const;
  const entries: Array<{
    candidate: TopicCandidate;
    topic: string;
    questions: Array<{ id: string; owner: string; text: string; privateInput: boolean }>;
  }> = [];
  for (const candidate of ctx.candidates) {
    // A record the egress rule keeps home is skipped before the cap.
    if (!mayShareRecord(ctx.cfg, use, candidate.private)) continue;
    const topic = holdingTopic(ctx, candidate);
    if (topic === null) continue;
    const questions = openQuestions(ctx, use, topic)
      .filter((question) => question.createdAt < candidate.at)
      .slice(0, TOPIC_DECISION_LIMITS.topicOptionsPerQuestion);
    if (questions.length === 0) continue;
    if (ctx.asked.has(use, resolutionSubject(candidate.id, questions))) continue;
    entries.push({ candidate, topic, questions });
  }
  if (entries.length > TOPIC_DECISION_LIMITS.recordsPerPass) {
    entries.length = TOPIC_DECISION_LIMITS.recordsPerPass;
  }
  for (const entry of entries) {
    if (!mayStartRequest(ctx.clock(), ctx.until, ctx.cfg.timeoutMs)) return;
    // One request per record: each record's option set is its own.
    // oxlint-disable-next-line no-await-in-loop
    await runResolutionRequest(ctx, use, entry);
  }
}

async function runResolutionRequest(
  ctx: PassContext,
  use: "question_resolved",
  entry: {
    candidate: TopicCandidate;
    topic: string;
    questions: Array<{ id: string; owner: string; text: string; privateInput: boolean }>;
  },
): Promise<void> {
  const questionsState = Object.fromEntries(
    entry.questions.map((question, i) => [
      `Q${i}`,
      clip(question.text, TOPIC_DECISION_LIMITS.headFieldClipChars),
    ]),
  );
  const criteriaKeys = entry.questions.map((question, i) => `Q${i}`);
  // The state carries the record beside the topic's question texts, and
  // the budget is measured over both.
  const built = buildCandidateState({
    candidates: [recordCandidate(ctx, use, entry.candidate)],
    prefix: QUESTION_RESOLVED_QUESTIONS.recordPrefix,
    clipChars: TOPIC_DECISION_LIMITS.recordClipChars,
    maxStateTokens: ctx.cfg.maxStateTokens,
    frame: (texts) => ({
      records: {
        R0: { topic: headFields(ctx, use, entry.topic)?.title ?? "", text: texts["R0"] ?? "" },
      },
      questions: questionsState,
    }),
  });
  if (built.kind !== "ok") return;
  const state = built.state;
  const result = await runDecision<{ recordId: string }>(
    use,
    () => ({
      kind: "ok",
      state,
      candidateCount: 1,
      context: { recordId: entry.candidate.id },
    }),
    () => ({
      [QUESTION_RESOLVED_QUESTIONS.answersId(0)]: QUESTION_RESOLVED_QUESTIONS.answers(
        0,
        criteriaKeys,
      ),
    }),
    {
      config: ctx.cfg,
      timeoutMs: requestTimeoutMs(ctx),
      ...requestOptions(ctx, (response) => {
        const details: Record<string, unknown> = {
          record_ids: [
            mayShareRecord(ctx.cfg, use, entry.candidate.private)
              ? entry.candidate.id
              : WITHHELD_ID,
          ],
          question_ids: entry.questions.map((question) => question.id),
        };
        if (response !== null) {
          const a = response.answers[QUESTION_RESOLVED_QUESTIONS.answersId(0)];
          const pick = a?.valid === true ? choiceConfidence(a) : null;
          details["chosen"] = pick?.key ?? null;
          details["probability"] = pick?.confidence ?? null;
        }
        return details;
      }),
    },
  );
  if (result.status !== "ok") return;
  const a = result.response.answers[QUESTION_RESOLVED_QUESTIONS.answersId(0)];
  if (a?.valid !== true) return;
  const pick = choiceConfidence(a);
  // An answer that proposes nothing is entered in the asked set.
  if (
    result.mode !== "enforce" ||
    pick === null ||
    pick.confidence < appliedThreshold(ctx.cfg, use, result.answeredBy.model, "resolved_min") ||
    pick.key === QUESTION_RESOLVED_QUESTIONS.noneOption
  ) {
    ctx.asked.add(
      use,
      resolutionSubject(entry.candidate.id, entry.questions),
      { model: result.answeredBy.model, mode: result.mode },
      entry.candidate.at,
    );
    return;
  }
  const chosen = entry.questions[Number(pick.key.slice(1))]!;
  ctx.out.resolutions.set(entry.candidate.id, {
    topic: entry.topic,
    question: chosen.id,
    owner: chosen.owner,
    // Every question offered and the topic title are inputs of the answer.
    privateInput:
      entry.questions.some((question) => question.privateInput) ||
      headIsPrivateInput(ctx, use, entry.topic, ["title"]),
    verdict: verdictBody(use, result.response, result.answeredBy.provider, pick.confidence),
  });
}

// ----- milestone_done --------------------------------------------------------

/** The topic's open milestones: nothing proposed or marked done yet. */
function openMilestones(
  ctx: PassContext,
  use: "milestone_done",
  topicId: string,
): Array<{ id: string; owner: string; text: string; createdAt: number; privateInput: boolean }> {
  const topic = ctx.fold.topics.get(topicId);
  return (topic?.items ?? [])
    .filter(
      (item) =>
        item.kind === "milestone" &&
        item.done === undefined &&
        item.doneProposed === undefined &&
        // A private milestone (or one of a private topic) is not asked
        // about when its text may not leave the machine.
        mayShareRecord(ctx.cfg, use, item.private || topic!.private),
    )
    .map((item) => ({
      id: item.id,
      owner: item.owner,
      text: stripPrivateRegions(item.text),
      createdAt: item.createdAt,
      privateInput: itemIsPrivateInput(ctx, use, item, topic!.private),
    }));
}

/**
 * `milestone_done` (design D10): `noul` per open milestone of a topic
 * with held records newer than the milestone, one request per
 * milestone; the state carries the milestone text and up to 5 of the
 * newest held record texts. p(yes) at or above `done_min` becomes a
 * completion verdict; the `milestone-done` proposal record is written
 * under the planning lock, never with evidence, so the fold shows
 * "looks done, confirm" and the milestone stays open. Everything else
 * proposes nothing.
 */
async function decideCompletions(ctx: PassContext): Promise<void> {
  const use = "milestone_done" as const;
  const entries: Array<{
    topic: string;
    milestone: { id: string; owner: string; text: string; privateInput: boolean };
    members: ReadonlyArray<TopicCandidate>;
  }> = [];
  // `ctx.candidates` is already in the pass's order (`newestPresentFirst`:
  // newest first, records dated after the run behind every present one),
  // and a filter keeps it.
  const rank = new Map(ctx.candidates.map((c, i) => [c.id, i]));
  for (const topicId of [...ctx.fold.topics.keys()].toSorted()) {
    const milestones = openMilestones(ctx, use, topicId);
    if (milestones.length === 0) continue;
    // Evidence the egress rule keeps home takes none of the shown slots.
    const members = ctx.candidates.filter(
      (c) => mayShareRecord(ctx.cfg, use, c.private) && holdingTopic(ctx, c) === topicId,
    );
    for (const milestone of milestones) {
      const newer = members.filter((c) => c.at > milestone.createdAt);
      if (newer.length === 0) continue;
      const shown = newer.slice(0, 5);
      if (ctx.asked.has(use, completionSubject(milestone, shown))) continue;
      entries.push({ topic: topicId, milestone, members: shown });
    }
  }
  // In the same order by the first record shown: a milestone with fresh
  // evidence is asked before one whose evidence is old, one with only
  // future-dated evidence last.
  const ordered = entries
    .toSorted((x, y) => rank.get(x.members[0]!.id)! - rank.get(y.members[0]!.id)!)
    .slice(0, TOPIC_DECISION_LIMITS.recordsPerPass);
  for (const entry of ordered) {
    if (!mayStartRequest(ctx.clock(), ctx.until, ctx.cfg.timeoutMs)) return;
    // One request per milestone: the state is the milestone's own.
    // oxlint-disable-next-line no-await-in-loop
    await runCompletionRequest(ctx, use, entry);
  }
}

async function runCompletionRequest(
  ctx: PassContext,
  use: "milestone_done",
  entry: {
    topic: string;
    milestone: { id: string; owner: string; text: string; privateInput: boolean };
    members: ReadonlyArray<TopicCandidate>;
  },
): Promise<void> {
  const built = buildCandidateState({
    candidates: entry.members.map((m) => recordCandidate(ctx, use, m)),
    prefix: MILESTONE_DONE_QUESTIONS.recordPrefix,
    clipChars: TOPIC_DECISION_LIMITS.groupMemberClipChars,
    maxStateTokens: ctx.cfg.maxStateTokens,
    // The milestone text rides the state too: the budget counts it.
    frame: (texts) => ({
      milestones: { M0: clip(entry.milestone.text, TOPIC_DECISION_LIMITS.headFieldClipChars) },
      records: texts,
    }),
  });
  if (built.kind !== "ok") return;
  const questions: Record<string, DecisionNoulQuestion> = {
    [MILESTONE_DONE_QUESTIONS.doneId(0)]: MILESTONE_DONE_QUESTIONS.done(0),
  };
  const state = built.state;
  const result = await runDecision<{ milestoneId: string }>(
    use,
    () => ({
      kind: "ok",
      state,
      candidateCount: built.included.length,
      context: { milestoneId: entry.milestone.id },
    }),
    () => questions,
    {
      config: ctx.cfg,
      timeoutMs: requestTimeoutMs(ctx),
      ...requestOptions(ctx, (response) => {
        const details: Record<string, unknown> = {
          milestone_ids: [entry.milestone.id],
          record_ids: entry.members.map((m) =>
            mayShareRecord(ctx.cfg, use, m.private) ? m.id : WITHHELD_ID,
          ),
        };
        if (response !== null) {
          details["p_yes"] = noulProbability(response.answers[MILESTONE_DONE_QUESTIONS.doneId(0)]);
        }
        return details;
      }),
    },
  );
  if (result.status !== "ok") return;
  const p = noulProbability(result.response.answers[MILESTONE_DONE_QUESTIONS.doneId(0)]);
  if (p === null) return;
  // "Not done" (or shadow, or below the threshold) proposes nothing: it is
  // entered in the asked set until newer evidence arrives.
  if (
    result.mode !== "enforce" ||
    p < appliedThreshold(ctx.cfg, use, result.answeredBy.model, "done_min")
  ) {
    ctx.asked.add(
      use,
      completionSubject(entry.milestone, entry.members),
      { model: result.answeredBy.model, mode: result.mode },
      entry.members[0]?.at ?? 0,
    );
    return;
  }
  ctx.out.completions.push({
    topic: entry.topic,
    milestone: entry.milestone.id,
    owner: entry.milestone.owner,
    // The milestone text and every evidence record the egress rule let
    // through are inputs of the answer.
    privateInput:
      entry.milestone.privateInput || built.included.some((index) => entry.members[index]!.private),
    verdict: verdictBody(use, result.response, result.answeredBy.provider, p),
  });
}

export { decideEventKinds, decideResolutions, decideCompletions };