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
9.1 KB
Raw Blame
/**
 * The minimum request time in the hook uses (design D20): `head_select`
 * and `neighbour_relevant` start no request when less than
 * `MIN_REQUEST_MS` of the hook budget is left, and keep the
 * deterministic fallback. The floor holds for each attempt of the
 * provider chain, not only for the hook budget as a whole.
 */

import { afterEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { runHeadSelect } from "../../../src/core/agent-context/head-select.ts";
import { runNeighbourRelevant } from "../../../src/core/agent-context/neighbour-relevant.ts";
import { resolveDecisionModelConfig } from "../../../src/core/decision-model/config.ts";
import { MIN_REQUEST_MS } from "../../../src/core/decision-model/request-floor.ts";
import { foldTopics, type TopicState } from "../../../src/core/topics/fold.ts";
import type { StoreRecord } from "../../../src/core/store/envelope.ts";
import { formatHlc } from "../../../src/core/store/hlc.ts";
import { FAKE_DECISION_KEY } from "../../helpers/fake-credentials.ts";
import { listDecisionModelCalls } from "../../../src/core/decision-model/record.ts";
import { FakeDecisionProvider, startFakeSystemOne } from "../../helpers/fake-decision-provider.ts";

const dirs: string[] = [];
afterEach(() => {
  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
});

const TOPIC = "01KA0000000000000000000001";
/**
 * Hook time well above the floor: the budget runs from the request's
 * start, so the few milliseconds spent preparing it count, and an exact
 * floor would leave the request to chance.
 */
const ENOUGH_MS = MIN_REQUEST_MS * 4;

function config(uses: string, hookBudgetMs?: number) {
  const vault = mkdtempSync(join(tmpdir(), "osb-floor-hooks-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  dirs.push(vault);
  return resolveDecisionModelConfig({
    env: { O2B_TEST_FLOOR_KEY: FAKE_DECISION_KEY } as NodeJS.ProcessEnv,
    config: {
      decision_model_enabled: "true",
      decision_model_provider: "compatible",
      decision_model_base_url: "https://decide.invalid/v1",
      decision_model_id: "floor-model",
      decision_model_env_key: "O2B_TEST_FLOOR_KEY",
      decision_model_uses: uses,
      ...(hookBudgetMs !== undefined
        ? { decision_model_hook_budget_ms: String(hookBudgetMs) }
        : {}),
    },
    vault,
    thresholdsPath: null,
  });
}

/**
 * A two-entry chain: a loopback server that never answers first, one
 * that answers second. Returns the config, its vault and both servers.
 */
async function hangingChain(uses: string) {
  const vault = mkdtempSync(join(tmpdir(), "osb-floor-hooks-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  dirs.push(vault);
  const hang = await startFakeSystemOne();
  const fast = await startFakeSystemOne();
  hang.setReply(() => ({ hang: true }));
  const env = {
    O2B_TEST_FLOOR_KEY: FAKE_DECISION_KEY,
    O2B_TEST_FLOOR_SECOND_KEY: FAKE_DECISION_KEY,
  } as NodeJS.ProcessEnv;
  const cfg = resolveDecisionModelConfig({
    env,
    config: {
      decision_model_enabled: "true",
      decision_model_providers: "compatible,typesafe",
      decision_model_base_url: hang.url,
      decision_model_id: "floor-model",
      decision_model_env_key: "O2B_TEST_FLOOR_KEY",
      decision_model_providers_typesafe_base_url: fast.url,
      decision_model_providers_typesafe_id: "floor-fallback",
      decision_model_providers_typesafe_env_key: "O2B_TEST_FLOOR_SECOND_KEY",
      decision_model_uses: uses,
    },
    vault,
    thresholdsPath: null,
  });
  return { cfg, env, vault, hang, fast };
}

/** Waits (bounded) until the vault holds `count` call records. */
async function recordsLanded(vault: string, count: number): Promise<void> {
  for (let i = 0; i < 500 && listDecisionModelCalls(vault).length < count; i++) {
    // oxlint-disable-next-line no-await-in-loop -- polling a background write
    await new Promise((r) => setTimeout(r, 10));
  }
}

function head(): TopicState {
  const record = {
    v: 1,
    id: "rec-1",
    hlc: formatHlc({ physical: Date.UTC(2026, 11, 1), counter: 0 }),
    device: "dev-a",
    agent: "seed",
    kind: "topic-create",
    scope: "project:o2b",
    topic: TOPIC,
    sum: "0".repeat(64),
    body: { authority: "agent", title: "Shard writer", scope: "project:o2b" },
  } as unknown as StoreRecord;
  return foldTopics([record]).topics.get(TOPIC)!;
}

describe("the minimum request time in the hook uses", () => {
  test("head_select starts a request with time to spare and none with less than the minimum", async () => {
    const cfg = config("head_select:shadow");
    const enough = new FakeDecisionProvider({});
    await runHeadSelect({
      config: cfg,
      heads: [head()],
      request: { project: "o2b", branch: null },
      remainingMs: ENOUGH_MS,
      provider: enough,
    });
    expect(enough.requests).toHaveLength(1);
    const short = new FakeDecisionProvider({});
    const out = await runHeadSelect({
      config: cfg,
      heads: [head()],
      request: { project: "o2b", branch: null },
      remainingMs: MIN_REQUEST_MS - 1,
      provider: short,
    });
    expect(short.requests).toEqual([]);
    expect(out.applied).toBe(false);
  });

  test("neighbour_relevant starts no request with less than the minimum left", async () => {
    const cfg = config("neighbour_relevant:shadow");
    const candidate = {
      record: "rec-2",
      kind: "log-entry",
      topic: TOPIC,
      topicTitle: "Shard writer",
      text: "The shard writer refactor landed",
      seq: 1,
      device: "dev-a",
      agent: "seed",
      private: false,
      titlePrivate: false,
    };
    const enough = new FakeDecisionProvider({});
    await runNeighbourRelevant({
      config: cfg,
      candidates: [candidate],
      prompt: "what changed in the shard writer",
      remainingMs: ENOUGH_MS,
      provider: enough,
    });
    expect(enough.requests).toHaveLength(1);
    const short = new FakeDecisionProvider({});
    const out = await runNeighbourRelevant({
      config: cfg,
      candidates: [candidate],
      prompt: "what changed in the shard writer",
      remainingMs: MIN_REQUEST_MS - 1,
      provider: short,
    });
    expect(short.requests).toEqual([]);
    expect(out.applied).toBe(false);
  });

  test("a hook budget below the minimum starts no request, however much hook time is left", async () => {
    const heads = new FakeDecisionProvider({});
    const selected = await runHeadSelect({
      config: config("head_select:shadow", MIN_REQUEST_MS - 1),
      heads: [head()],
      request: { project: "o2b", branch: null },
      remainingMs: 10_000,
      provider: heads,
    });
    expect(heads.requests).toEqual([]);
    expect(selected.applied).toBe(false);
    const neighbours = new FakeDecisionProvider({});
    await runNeighbourRelevant({
      config: config("neighbour_relevant:shadow", MIN_REQUEST_MS - 1),
      candidates: [
        {
          record: "rec-2",
          kind: "log-entry",
          topic: TOPIC,
          topicTitle: "Shard writer",
          text: "The shard writer refactor landed",
          seq: 1,
          device: "dev-a",
          agent: "seed",
          private: false,
          titlePrivate: false,
        },
      ],
      prompt: "what changed in the shard writer",
      remainingMs: 10_000,
      provider: neighbours,
    });
    expect(neighbours.requests).toEqual([]);
  });

  test("each attempt of the chain gets the floor: an entry whose share would fall below it is not asked", async () => {
    // Room for one attempt: an even split would give each entry less
    // than the floor, so the first gets it all and the second none.
    const remainingMs = MIN_REQUEST_MS * 2 - 1;
    const heads = await hangingChain("head_select:shadow");
    try {
      const out = await runHeadSelect({
        config: heads.cfg,
        heads: [head()],
        request: { project: "o2b", branch: null },
        remainingMs,
        env: heads.env,
      });
      expect(out.applied).toBe(false);
      await recordsLanded(heads.vault, 1);
      expect(heads.hang.requests).toHaveLength(1);
      expect(heads.fast.requests).toHaveLength(0);
    } finally {
      await heads.hang.close();
      await heads.fast.close();
    }
    const neighbours = await hangingChain("neighbour_relevant:shadow");
    try {
      const out = await runNeighbourRelevant({
        config: neighbours.cfg,
        candidates: [
          {
            record: "rec-2",
            kind: "log-entry",
            topic: TOPIC,
            topicTitle: "Shard writer",
            text: "The shard writer refactor landed",
            seq: 1,
            device: "dev-a",
            agent: "seed",
            private: false,
            titlePrivate: false,
          },
        ],
        prompt: "what changed in the shard writer",
        remainingMs,
        env: neighbours.env,
      });
      expect(out.applied).toBe(false);
      await recordsLanded(neighbours.vault, 1);
      expect(neighbours.hang.requests).toHaveLength(1);
      expect(neighbours.fast.requests).toHaveLength(0);
    } finally {
      await neighbours.hang.close();
      await neighbours.fast.close();
    }
  });
});