switchroom 0.17.6 → 0.18.3

package/telegram-plugin/tests/memory-legibility.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest'
+import {
+  classifyMemoryToolCall,
+  detectMemoryLegibilityEvent,
+  isMemoryLegibilityEnabled,
+  renderMemoryLegibilityLine,
+  MemoryLegibilityStager,
+  CREATE_DIRECTIVE_TOOL,
+  INVALIDATE_MEMORY_TOOL,
+  UPDATE_MEMORY_TOOL,
+} from '../memory-legibility.js'
+
+describe('isMemoryLegibilityEnabled — default-ON kill switch', () => {
+  it('is ON when unset (fresh setup / defaults principle)', () => {
+    expect(isMemoryLegibilityEnabled(undefined)).toBe(true)
+  })
+  it('is ON for any value except the literal "0"', () => {
+    expect(isMemoryLegibilityEnabled('1')).toBe(true)
+    expect(isMemoryLegibilityEnabled('')).toBe(true)
+    expect(isMemoryLegibilityEnabled('true')).toBe(true)
+  })
+  it('is OFF only for "0"', () => {
+    expect(isMemoryLegibilityEnabled('0')).toBe(false)
+  })
+})
+
+describe('classifyMemoryToolCall — the reusable "did a material memory op happen?" primitive (#2848 Stage B imports this)', () => {
+  it('classifies create_directive as directive-create', () => {
+    expect(classifyMemoryToolCall(CREATE_DIRECTIVE_TOOL, { content: 'x', name: 'y' })).toBe(
+      'directive-create',
+    )
+  })
+
+  it('classifies invalidate_memory as memory-invalidate', () => {
+    expect(classifyMemoryToolCall(INVALIDATE_MEMORY_TOOL, { memory_id: 'm1' })).toBe(
+      'memory-invalidate',
+    )
+  })
+
+  it('classifies update_memory as memory-invalidate ONLY when it applies the demote-from-recall tag', () => {
+    expect(
+      classifyMemoryToolCall(UPDATE_MEMORY_TOOL, {
+        memory_id: 'm1',
+        add_tags: ['[demote-from-recall]'],
+      }),
+    ).toBe('memory-invalidate')
+    // bracket-less + case variant still matches
+    expect(
+      classifyMemoryToolCall(UPDATE_MEMORY_TOOL, { add_tags: ['DEMOTE-FROM-RECALL'] }),
+    ).toBe('memory-invalidate')
+  })
+
+  it('does NOT classify a benign update_memory edit (no demote tag) — material-only', () => {
+    expect(
+      classifyMemoryToolCall(UPDATE_MEMORY_TOOL, { memory_id: 'm1', add_tags: ['urgent'] }),
+    ).toBeNull()
+    expect(classifyMemoryToolCall(UPDATE_MEMORY_TOOL, { content: 'edited' })).toBeNull()
+  })
+
+  it('does NOT classify ordinary recall / reflect / retain — no line on routine memory ops', () => {
+    for (const tool of [
+      'mcp__hindsight__recall',
+      'mcp__hindsight__reflect',
+      'mcp__hindsight__retain',
+      'mcp__hindsight__sync_retain',
+      'mcp__hindsight__list_directives',
+      'Bash',
+      'Read',
+    ]) {
+      expect(classifyMemoryToolCall(tool, { query: 'x' })).toBeNull()
+    }
+  })
+})
+
+describe('detectMemoryLegibilityEvent — extracts the human detail', () => {
+  it('reads directive body from the real `content` wire field', () => {
+    expect(
+      detectMemoryLegibilityEvent(CREATE_DIRECTIVE_TOOL, {
+        name: 'ts-pref',
+        content: 'Always prefer TypeScript for this user',
+      }),
+    ).toEqual({ kind: 'remembered', detail: 'Always prefer TypeScript for this user' })
+  })
+
+  it('falls back to `text` then `name` when `content` is absent', () => {
+    expect(detectMemoryLegibilityEvent(CREATE_DIRECTIVE_TOOL, { text: 'Prefer TS' })).toEqual({
+      kind: 'remembered',
+      detail: 'Prefer TS',
+    })
+    expect(detectMemoryLegibilityEvent(CREATE_DIRECTIVE_TOOL, { name: 'Prefer TS' })).toEqual({
+      kind: 'remembered',
+      detail: 'Prefer TS',
+    })
+  })
+
+  it('surfaces an invalidate reason but omits the opaque memory_id', () => {
+    expect(
+      detectMemoryLegibilityEvent(INVALIDATE_MEMORY_TOOL, {
+        memory_id: 'mem_abc123',
+        reason: 'superseded deploy runbook',
+      }),
+    ).toEqual({ kind: 'forgot', detail: 'superseded deploy runbook' })
+    // no reason → empty detail (render uses the bare fallback), never the id
+    expect(detectMemoryLegibilityEvent(INVALIDATE_MEMORY_TOOL, { memory_id: 'mem_abc' })).toEqual({
+      kind: 'forgot',
+      detail: '',
+    })
+  })
+
+  it('returns null for non-material tools', () => {
+    expect(detectMemoryLegibilityEvent('mcp__hindsight__recall', { query: 'x' })).toBeNull()
+    expect(detectMemoryLegibilityEvent(UPDATE_MEMORY_TOOL, { content: 'edit' })).toBeNull()
+  })
+
+  it('tolerates undefined input', () => {
+    expect(detectMemoryLegibilityEvent(CREATE_DIRECTIVE_TOOL, undefined)).toEqual({
+      kind: 'remembered',
+      detail: '',
+    })
+  })
+})
+
+describe('MemoryLegibilityStager — confirm-before-legibility (Fix 1.3, #2903)', () => {
+  const evt = { kind: 'remembered' as const, detail: 'Always prefer TypeScript' }
+
+  it('sends the line only on a CONFIRMED-successful tool_result', () => {
+    const s = new MemoryLegibilityStager<{ chatId: string }>()
+    s.stage('toolu_ok', evt, { chatId: '123' })
+    expect(s.size).toBe(1)
+    const resolved = s.confirm('toolu_ok', undefined) // undefined isError = success
+    expect(resolved).not.toBeNull()
+    expect(resolved!.event).toEqual(evt)
+    expect(resolved!.meta).toEqual({ chatId: '123' })
+    expect(s.size).toBe(0) // consumed
+  })
+
+  it('does NOT send on a FAILED write — a failed create_directive shows NO line', () => {
+    const s = new MemoryLegibilityStager<{ chatId: string }>()
+    s.stage('toolu_fail', evt, { chatId: '123' })
+    // is_error:true on the tool_result (engine down / isError envelope)
+    const resolved = s.confirm('toolu_fail', true)
+    expect(resolved).toBeNull()
+    // the staged entry is consumed even on failure — no leak, no later re-send
+    expect(s.size).toBe(0)
+  })
+
+  it('returns null when no event was staged for the id (non-material tool result)', () => {
+    const s = new MemoryLegibilityStager<{ chatId: string }>()
+    expect(s.confirm('unknown-id', undefined)).toBeNull()
+  })
+
+  it('returns null for an empty/missing toolUseId (cannot correlate → no unconfirmed send)', () => {
+    const s = new MemoryLegibilityStager<{ chatId: string }>()
+    expect(s.confirm('', undefined)).toBeNull()
+    expect(s.confirm(null, undefined)).toBeNull()
+    expect(s.confirm(undefined, undefined)).toBeNull()
+  })
+
+  it('evicts the oldest staged entry past the cap so a crashy turn cannot leak', () => {
+    const s = new MemoryLegibilityStager<{ n: number }>(2)
+    s.stage('a', evt, { n: 1 })
+    s.stage('b', evt, { n: 2 })
+    s.stage('c', evt, { n: 3 }) // evicts 'a'
+    expect(s.size).toBe(2)
+    expect(s.confirm('a', undefined)).toBeNull() // evicted
+    expect(s.confirm('c', undefined)).not.toBeNull()
+  })
+})
+
+describe('renderMemoryLegibilityLine — terse HTML one-liner', () => {
+  it('renders a remembered directive in quotes', () => {
+    expect(
+      renderMemoryLegibilityLine({ kind: 'remembered', detail: 'Always prefer TypeScript' }),
+    ).toBe('📌 <i>remembered:</i> "Always prefer TypeScript"')
+  })
+
+  it('renders a forgot line with the reason', () => {
+    expect(renderMemoryLegibilityLine({ kind: 'forgot', detail: 'superseded runbook' })).toBe(
+      '✂️ <i>forgot:</i> superseded runbook',
+    )
+  })
+
+  it('uses a bare fallback when there is no legible detail', () => {
+    expect(renderMemoryLegibilityLine({ kind: 'remembered', detail: '' })).toBe(
+      '📌 <i>remembered a new directive.</i>',
+    )
+    expect(renderMemoryLegibilityLine({ kind: 'forgot', detail: '   ' })).toBe(
+      '✂️ <i>forgot a memory.</i>',
+    )
+  })
+
+  it('HTML-escapes the detail so it cannot break parse_mode:HTML', () => {
+    const out = renderMemoryLegibilityLine({
+      kind: 'remembered',
+      detail: 'use <b> & compare a < b',
+    })
+    expect(out).toBe('📌 <i>remembered:</i> "use &lt;b&gt; &amp; compare a &lt; b"')
+    // the only literal < / > left are the wrapper <i> tags
+    expect(out).not.toContain('<b>')
+  })
+
+  it('strips markdown and collapses whitespace before truncating', () => {
+    const out = renderMemoryLegibilityLine({
+      kind: 'remembered',
+      detail: '**Always**   prefer  `TypeScript`',
+    })
+    expect(out).toBe('📌 <i>remembered:</i> "Always prefer TypeScript"')
+  })
+
+  it('truncates very long directive bodies with an ellipsis', () => {
+    const long = 'x'.repeat(400)
+    const out = renderMemoryLegibilityLine({ kind: 'remembered', detail: long })
+    expect(out.length).toBeLessThan(220)
+    expect(out).toContain('…')
+  })
+})

package/telegram-plugin/tests/mental-model-propose-callback-gate.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Contract pins for `handleMentalModelProposeCallback` — the operator-tap
+ * resolver for a mental-model proposal card (hindsight Phase 5, Fix 6.1).
+ *
+ * These are source-inspection pins (the handler needs a live grammY Context +
+ * hostd dispatch to run, so we assert its structure the same way the vault
+ * callback posture tests do). Load-bearing invariants:
+ *
+ *   1. The `allowFrom` authorization gate is the FIRST thing the handler does —
+ *      a tap from anyone not on the operator allow-list is refused before any
+ *      pending lookup, pending delete, or hostd dispatch runs. This is the
+ *      "an agent can never self-approve" boundary.
+ *   2. The TTL is enforced at TAP time, not only on the next propose's sweep —
+ *      a card past MENTAL_MODEL_PROPOSE_TTL_MS is refused and its keyboard is
+ *      edited away, even when no fresh proposal has swept it.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8')
+
+function proposeCallbackBlock(): string {
+  return (
+    gatewaySrc.split('async function handleMentalModelProposeCallback')[1]?.split('\nasync function')[0] ?? ''
+  )
+}
+
+describe('handleMentalModelProposeCallback — authorization gate', () => {
+  it('refuses a tap from a non-operator via the allowFrom allow-list FIRST', () => {
+    const block = proposeCallbackBlock()
+    expect(block).toMatch(/if \(!access\.allowFrom\.includes\(senderId\)\)/)
+    expect(block).toMatch(/Not authorized/)
+    // The allowFrom guard must precede the pending lookup / delete: no state
+    // mutation before authorization.
+    const beforeGuard = block.split('access.allowFrom.includes(senderId)')[0] ?? ''
+    expect(beforeGuard).not.toMatch(/pendingMentalModelProposes\.get/)
+    expect(beforeGuard).not.toMatch(/pendingMentalModelProposes\.delete/)
+  })
+})
+
+describe('handleMentalModelProposeCallback — TTL enforced at tap time', () => {
+  it('checks staged_at against MENTAL_MODEL_PROPOSE_TTL_MS at tap and edits the card away', () => {
+    const block = proposeCallbackBlock()
+    expect(block).toMatch(/Date\.now\(\) - pending\.staged_at > MENTAL_MODEL_PROPOSE_TTL_MS/)
+    // The expired branch deletes the pending entry and clears the keyboard so a
+    // stale card can't be tapped into an approval.
+    const ttlBranch =
+      block.split('Date.now() - pending.staged_at > MENTAL_MODEL_PROPOSE_TTL_MS')[1]?.split('Single-shot')[0] ?? ''
+    expect(ttlBranch).toMatch(/pendingMentalModelProposes\.delete\(stageId\)/)
+    expect(ttlBranch).toMatch(/expired/)
+    expect(ttlBranch).toMatch(/inline_keyboard: \[\]/)
+  })
+})
+
+describe('executeMentalModelPropose — schema caps enforced up-front', () => {
+  it('rejects an over-length source_query and an over-cap max_tokens before posting a card', () => {
+    const fn =
+      gatewaySrc.split('async function executeMentalModelPropose')[1]?.split('\nasync function')[0] ?? ''
+    expect(fn).toMatch(/source_query\.length > MENTAL_MODEL_SOURCE_QUERY_MAX/)
+    expect(fn).toMatch(/n > MENTAL_MODEL_MAX_TOKENS_CAP/)
+    // Caps mirror the schema (src/config/schema.ts): 2000 / 8192.
+    expect(gatewaySrc).toMatch(/MENTAL_MODEL_SOURCE_QUERY_MAX = 2000/)
+    expect(gatewaySrc).toMatch(/MENTAL_MODEL_MAX_TOKENS_CAP = 8192/)
+  })
+})

package/telegram-plugin/tests/mental-model-propose-card.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { renderMentalModelProposeCard } from "../gateway/mental-model-propose-card.js";
+
+/**
+ * The proposal RENDERS an operator approval card (hindsight Phase 5). Mirrors
+ * the vault-request-access card: agent name + model name + source query +
+ * rationale, with the same escaping discipline.
+ */
+describe("renderMentalModelProposeCard", () => {
+  it("renders a card carrying the agent, model name, source query, and rationale", () => {
+    const card = renderMentalModelProposeCard({
+      agent: "coach",
+      name: "training-plan-state",
+      source_query: "What is the athlete's current plan?",
+      reason: "I keep re-deriving the plan state every session",
+      refresh_after_consolidation: true,
+      max_tokens: 1024,
+    });
+    expect(card).toContain("proposes a mental model");
+    expect(card).toContain("coach");
+    // Model name rendered inside a code span (literal).
+    expect(card).toContain("`training-plan-state`");
+    expect(card).toContain("What is the athlete's current plan?");
+    expect(card).toContain("I keep re-deriving the plan state every session");
+    expect(card).toContain("refresh after consolidation: `on`");
+    // max_tokens is surfaced so the operator approves exactly what's applied.
+    expect(card).toContain("max tokens: `1024`");
+    // The card explains the approve/deny semantics so the operator can decide.
+    expect(card).toContain("Approve");
+    expect(card).toContain("Deny");
+    expect(card).toContain("memory.mental_models[]");
+  });
+
+  it("renders 'why: not provided' when no rationale is supplied (agent-side omission is visible)", () => {
+    const card = renderMentalModelProposeCard({
+      agent: "coach",
+      name: "plan",
+      source_query: "q",
+    });
+    expect(card).toContain("why: _not provided_");
+    expect(card).toContain("refresh after consolidation: `off`");
+    // No max_tokens on the proposal → the applied model inherits the default;
+    // render that explicitly rather than hiding the field.
+    expect(card).toContain("max tokens: `default`");
+  });
+
+  it("defuses a backtick in the model name so it can't break out of the code span", () => {
+    const card = renderMentalModelProposeCard({
+      agent: "coach",
+      name: "pl`an",
+      source_query: "q",
+    });
+    // The raw backtick must not survive verbatim inside the span.
+    expect(card).not.toContain("`pl`an`");
+  });
+});

package/telegram-plugin/tests/mental-model-propose-diff.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi } from "vitest";
+import { parseDocument } from "yaml";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  buildMentalModelAppendDiff,
+  readDeclaredMentalModelNames,
+} from "../gateway/mental-model-propose-diff.js";
+import { ensureDeclaredMentalModels } from "../../src/memory/hindsight.js";
+
+/** Apply a unified diff the way hostd does (git apply -p1) and return the
+ *  patched file contents, or null if the patch didn't apply. */
+function gitApply(before: string, diff: string): string | null {
+  const dir = mkdtempSync(join(tmpdir(), "mmp-apply-"));
+  try {
+    writeFileSync(join(dir, "switchroom.yaml"), before);
+    writeFileSync(join(dir, "patch.diff"), diff);
+    const init = spawnSync("git", ["init", "-q"], { cwd: dir });
+    if (init.status !== 0) return null;
+    const r = spawnSync(
+      "git",
+      ["apply", "--whitespace=nowarn", "--recount", "-p1", "patch.diff"],
+      { cwd: dir, encoding: "utf-8" },
+    );
+    if (r.status !== 0) return null;
+    return readFileSync(join(dir, "switchroom.yaml"), "utf-8");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * hindsight Phase 5 — the persistence primitive for the agent-proposes →
+ * human-approves mental-model flow. An approved proposal must become a
+ * first-class DECLARED model in agents.<agent>.memory.mental_models[] so the
+ * exact same #2874 ensure/reconcile path consumes it.
+ */
+
+const CONFIG_NO_MODELS = `agents:
+  coach:
+    persona: fitness
+    memory:
+      collection: coach-bank
+  lawyer:
+    persona: legal
+`;
+
+const CONFIG_WITH_MODELS = `agents:
+  coach:
+    persona: fitness
+    memory:
+      collection: coach-bank
+      mental_models:
+        - name: training-plan-state
+          source_query: What is the athlete's current plan?
+`;
+
+describe("readDeclaredMentalModelNames", () => {
+  it("returns [] when the agent has no declared models", () => {
+    expect(readDeclaredMentalModelNames(CONFIG_NO_MODELS, "coach")).toEqual([]);
+  });
+  it("reads the declared model names for the agent (and not siblings)", () => {
+    expect(readDeclaredMentalModelNames(CONFIG_WITH_MODELS, "coach")).toEqual([
+      "training-plan-state",
+    ]);
+    expect(readDeclaredMentalModelNames(CONFIG_WITH_MODELS, "lawyer")).toEqual([]);
+  });
+  it("never throws on unparseable config", () => {
+    expect(readDeclaredMentalModelNames(":\n  bad: [", "coach")).toEqual([]);
+  });
+});
+
+describe("buildMentalModelAppendDiff — appends the declaration", () => {
+  it("creates memory.mental_models[] when absent and appends the model", () => {
+    const r = buildMentalModelAppendDiff({
+      configText: CONFIG_NO_MODELS,
+      agentName: "coach",
+      spec: { name: "training-plan-state", source_query: "What is the plan?" },
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    // The appended `after` declares the model under the right agent.
+    expect(readDeclaredMentalModelNames(r.after, "coach")).toContain(
+      "training-plan-state",
+    );
+    // And the diff is a real git-apply-shaped unified diff.
+    expect(r.diff).toContain("--- a/switchroom.yaml");
+    expect(r.diff).toContain("+++ b/switchroom.yaml");
+    expect(r.diff).toContain("training-plan-state");
+  });
+
+  it("appends to an existing mental_models[] without dropping the prior model", () => {
+    const r = buildMentalModelAppendDiff({
+      configText: CONFIG_WITH_MODELS,
+      agentName: "coach",
+      spec: { name: "injury-history", source_query: "Which injuries?", max_tokens: 1024 },
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const names = readDeclaredMentalModelNames(r.after, "coach");
+    expect(names).toEqual(["training-plan-state", "injury-history"]);
+  });
+
+  it("only serialises knobs that are set (schema-clean minimal declaration)", () => {
+    const r = buildMentalModelAppendDiff({
+      configText: CONFIG_NO_MODELS,
+      agentName: "coach",
+      spec: { name: "plan", source_query: "q", refresh_after_consolidation: true },
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const model = (parseDocument(r.after).toJS() as any).agents.coach.memory.mental_models[0];
+    expect(model).toEqual({
+      name: "plan",
+      source_query: "q",
+      refresh_after_consolidation: true,
+    });
+    expect("max_tokens" in model).toBe(false);
+  });
+
+  it("the synthesized diff round-trips through git apply against the live config", () => {
+    const r = buildMentalModelAppendDiff({
+      configText: CONFIG_WITH_MODELS,
+      agentName: "coach",
+      spec: { name: "injury-history", source_query: "Which injuries?" },
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    // hostd applies with git apply; prove the patch actually lands.
+    const applied = gitApply(CONFIG_WITH_MODELS, r.diff);
+    expect(applied).not.toBeNull();
+    expect(readDeclaredMentalModelNames(applied!, "coach")).toEqual([
+      "training-plan-state",
+      "injury-history",
+    ]);
+  });
+});
+
+describe("buildMentalModelAppendDiff — guardrails", () => {
+  it("REJECTS a duplicate-name proposal (the idempotent-ensure key must be unique)", () => {
+    const r = buildMentalModelAppendDiff({
+      configText: CONFIG_WITH_MODELS,
+      agentName: "coach",
+      spec: { name: "training-plan-state", source_query: "different query" },
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toBe("duplicate");
+  });
+
+  it("REJECTS a proposal for an agent that is not in the config (never invents one)", () => {
+    const r = buildMentalModelAppendDiff({
+      configText: CONFIG_NO_MODELS,
+      agentName: "ghost",
+      spec: { name: "x", source_query: "q" },
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toBe("agent-not-found");
+  });
+});
+
+describe("appended declaration is consumed by #2874's ensure path", () => {
+  it("the appended model is ensured by ensureDeclaredMentalModels (create fired)", async () => {
+    const r = buildMentalModelAppendDiff({
+      configText: CONFIG_NO_MODELS,
+      agentName: "coach",
+      spec: { name: "training-plan-state", source_query: "What is the plan?" },
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+
+    // Read the newly-declared model set exactly as scaffold/reconcile would.
+    const declared = (parseDocument(r.after).toJS() as any).agents.coach.memory
+      .mental_models;
+
+    const mockFetch = vi
+      .fn()
+      // init
+      .mockResolvedValueOnce({ ok: true, headers: new Map([["mcp-session-id", "s"]]), text: async () => "" })
+      // list (empty → create)
+      .mockResolvedValueOnce({ ok: true, text: async () => `data: {"result":{"content":[{"text":${JSON.stringify(JSON.stringify({ items: [] }))}}]}}\n` })
+      // create
+      .mockResolvedValueOnce({ ok: true, text: async () => 'data: {"result":{"isError":false}}\n' });
+
+    const outcomes = await ensureDeclaredMentalModels(
+      "http://test.local/mcp/",
+      "coach-bank",
+      declared,
+      { fetchImpl: mockFetch as any },
+    );
+    expect(outcomes).toEqual([{ name: "training-plan-state", ok: true }]);
+    // create_mental_model actually fired with the declared source_query.
+    const createBody = JSON.parse(mockFetch.mock.calls[2][1].body);
+    expect(createBody.params.name).toBe("create_mental_model");
+    expect(createBody.params.arguments.name).toBe("training-plan-state");
+    expect(createBody.params.arguments.source_query).toBe("What is the plan?");
+  });
+});

package/telegram-plugin/tests/mental-model-propose-inbound-builders.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildMentalModelProposeAppliedInbound,
+  buildMentalModelProposeDeniedInbound,
+  buildMentalModelProposeFailedInbound,
+} from "../gateway/mental-model-propose-inbound-builders.js";
+
+/**
+ * The synthetic-inbound shapes are load-bearing: the bridge keys on
+ * `meta.source` to render `<channel source="...">` and resume the agent's turn.
+ * A drifted source string or dropped meta field silently breaks the wake-up.
+ */
+
+const ctx = {
+  agent: "coach",
+  name: "training-plan-state",
+  chat_id: "555",
+  threadId: 99,
+};
+
+describe("mental-model proposal synthetic inbounds", () => {
+  it("applied inbound carries source + forensic meta and threads the topic", () => {
+    const m = buildMentalModelProposeAppliedInbound({
+      ctx,
+      stageId: "st1",
+      operatorId: "op-7",
+      nowMs: 1234,
+    });
+    expect(m.type).toBe("inbound");
+    expect(m.chatId).toBe("555");
+    expect(m.threadId).toBe(99);
+    expect(m.meta.source).toBe("mental_model_proposal_applied");
+    expect(m.meta.agent).toBe("coach");
+    expect(m.meta.name).toBe("training-plan-state");
+    expect(m.meta.stage_id).toBe("st1");
+    expect(m.meta.operator_id).toBe("op-7");
+    expect(m.meta.message_thread_id).toBe("99");
+    expect(m.text).toContain("approved");
+    expect(m.text).toContain("training-plan-state");
+  });
+
+  it("denied inbound tells the agent NOTHING was written", () => {
+    const m = buildMentalModelProposeDeniedInbound({
+      ctx: { agent: "coach", name: "plan", chat_id: "1" },
+      stageId: "st2",
+      operatorId: "op-1",
+      nowMs: 5,
+    });
+    expect(m.meta.source).toBe("mental_model_proposal_denied");
+    expect(m.threadId).toBeUndefined();
+    expect(m.meta.message_thread_id).toBeUndefined();
+    expect(m.text).toContain("denied");
+    expect(m.text.toUpperCase()).toContain("NOTHING");
+  });
+
+  it("failed inbound is honest that the model did NOT land", () => {
+    const m = buildMentalModelProposeFailedInbound({
+      ctx: { agent: "coach", name: "plan", chat_id: "1" },
+      stageId: "st3",
+      operatorId: "op-1",
+      reason: "hostd down",
+      nowMs: 5,
+    });
+    expect(m.meta.source).toBe("mental_model_proposal_failed");
+    expect(m.text).toContain("hostd down");
+    expect(m.text).toContain("NOT");
+  });
+});