@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/chat/composer/translate.test.ts

@@ -0,0 +1,199 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * WHY: everything the composer sends is rewritten before it reaches omp, so a
+ * translation bug silently corrupts the user's prompt. `@file:` tokens are
+ * rewritten to omp's native file-mention syntax, and `@agent` tokens are
+ * stripped from the body and replaced by a delegation header. The edge cases
+ * that matter are the ones that decide whether a token is a mention at all:
+ * quoted paths with spaces, trailing prose punctuation, a bare path that must
+ * NOT be swallowed as an agent name, and a draft that is nothing but mentions.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { extractAgentMentions, translateAgentMentions, translateFileMentions } from '@/shared/lib/chat/composer/translate';
+
+const AGENTS = ['architect', 'sonic', 'Archivist'];
+
+describe('translateFileMentions', () => {
+  test('rewrites a bare @file: token to a native @path mention', () => {
+    expect(translateFileMentions('@file:src/a.ts')).toBe('@src/a.ts');
+    expect(translateFileMentions('read @file:src/lib/x.ts now')).toBe('read @src/lib/x.ts now');
+  });
+
+  test('rewrites a quoted @file: token, keeping the quotes', () => {
+    expect(translateFileMentions('@"file:my docs/a.ts"')).toBe('@"my docs/a.ts"');
+    expect(translateFileMentions('see @"file:a b.txt" end')).toBe('see @"a b.txt" end');
+  });
+
+  test('the quoted form is rewritten before the bare form can see it', () => {
+    // The bare regex needs `@file:` immediately; after the quoted pass the
+    // token is `@"..."`, so the two rules cannot fight over one mention.
+    expect(translateFileMentions('@"file:one two" @file:three')).toBe('@"one two" @three');
+  });
+
+  test('every opening delimiter qualifies, and all occurrences are rewritten', () => {
+    expect(translateFileMentions('(@file:a.ts)')).toBe('(@a.ts)');
+    expect(translateFileMentions('[@file:a.ts]')).toBe('[@a.ts]');
+    expect(translateFileMentions('{@file:a.ts}')).toBe('{@a.ts}');
+    expect(translateFileMentions('@file:a.ts and @file:b.ts')).toBe('@a.ts and @b.ts');
+  });
+
+  test('a mid-token @file: is left alone', () => {
+    expect(translateFileMentions('foo@file:a.ts')).toBe('foo@file:a.ts');
+  });
+
+  test('text with no file mentions is untouched', () => {
+    expect(translateFileMentions('plain text')).toBe('plain text');
+    expect(translateFileMentions('@sonic do it')).toBe('@sonic do it');
+    expect(translateFileMentions('')).toBe('');
+  });
+
+  test('a trailing period in the path is preserved', () => {
+    // A path can legitimately end in `.`, and the picker inserts a space, so
+    // no trailing-punctuation stripping happens here.
+    expect(translateFileMentions('@file:foo.test.ts')).toBe('@foo.test.ts');
+  });
+});
+
+describe('extractAgentMentions', () => {
+  test('a bare known name is matched with its span over @token', () => {
+    expect(extractAgentMentions('@architect do it', AGENTS)).toEqual([{ name: 'architect', start: 0, end: 10 }]);
+    expect(extractAgentMentions('see @sonic', AGENTS)).toEqual([{ name: 'sonic', start: 4, end: 10 }]);
+  });
+
+  test('name matching is case-insensitive but the original casing is kept', () => {
+    expect(extractAgentMentions('@Architect hi', AGENTS)).toEqual([{ name: 'Architect', start: 0, end: 10 }]);
+    expect(extractAgentMentions('@SONIC hi', AGENTS)).toEqual([{ name: 'SONIC', start: 0, end: 6 }]);
+  });
+
+  test('quoted tokens are matched verbatim, with the span covering the quotes', () => {
+    expect(extractAgentMentions('@"architect" hi', AGENTS)).toEqual([{ name: 'architect', start: 0, end: 12 }]);
+    expect(extractAgentMentions("@'sonic' hi", AGENTS)).toEqual([{ name: 'sonic', start: 0, end: 8 }]);
+  });
+
+  test('trailing prose punctuation is stripped before matching a bare token', () => {
+    // Span ends at the name, leaving the `.` in the draft.
+    expect(extractAgentMentions('ping @architect.', AGENTS)).toEqual([{ name: 'architect', start: 5, end: 15 }]);
+    expect(extractAgentMentions('@sonic, go', AGENTS)).toEqual([{ name: 'sonic', start: 0, end: 6 }]);
+    expect(extractAgentMentions('(@sonic)', AGENTS)).toEqual([{ name: 'sonic', start: 1, end: 7 }]);
+  });
+
+  test('a bare path is never swallowed as an agent name', () => {
+    // `build` is not in this pool, but even a known name must not match when
+    // the whole token is `build/x.ts`.
+    expect(extractAgentMentions('@build/x.ts', ['build'])).toEqual([]);
+    expect(extractAgentMentions('@sonic/x.ts', AGENTS)).toEqual([]);
+  });
+
+  test('a mid-token or unknown mention yields nothing', () => {
+    expect(extractAgentMentions('foo@architect', AGENTS)).toEqual([]);
+    expect(extractAgentMentions('@nobody hi', AGENTS)).toEqual([]);
+    expect(extractAgentMentions('no mentions here', AGENTS)).toEqual([]);
+  });
+
+  test('an empty agent pool matches nothing', () => {
+    expect(extractAgentMentions('@architect', [])).toEqual([]);
+  });
+
+  test('every occurrence is returned, duplicates included', () => {
+    expect(extractAgentMentions('@sonic and @sonic', AGENTS)).toEqual([
+      { name: 'sonic', start: 0, end: 6 },
+      { name: 'sonic', start: 11, end: 17 },
+    ]);
+  });
+
+  test('a quoted unknown name is rejected like a bare one', () => {
+    expect(extractAgentMentions('@"nobody" hi', AGENTS)).toEqual([]);
+  });
+});
+
+describe('translateAgentMentions', () => {
+  const header = (ids: string, quoted: string): string =>
+    `Use the task tool to delegate this request to the following oh-my-pi subagent(s): ${quoted} (agent id: ${ids}).\n\n`;
+
+  test('no mentions leaves the text untouched and the list empty', () => {
+    expect(translateAgentMentions('just a prompt', AGENTS)).toEqual({ text: 'just a prompt', agents: [] });
+    expect(translateAgentMentions('@nobody', AGENTS)).toEqual({ text: '@nobody', agents: [] });
+  });
+
+  test('a mention is removed from the body and named in the header', () => {
+    expect(translateAgentMentions('@architect fix the bug', AGENTS)).toEqual({
+      text: `${header('architect', '`architect`')}fix the bug`,
+      agents: ['architect'],
+    });
+  });
+
+  test('several agents are listed in encounter order', () => {
+    expect(translateAgentMentions('@sonic then @architect go', AGENTS)).toEqual({
+      text: `${header('sonic, architect', '`sonic`, `architect`')}then go`,
+      agents: ['sonic', 'architect'],
+    });
+  });
+
+  test('duplicate mentions collapse to one agent but are all removed from the body', () => {
+    expect(translateAgentMentions('@sonic and @sonic again', AGENTS)).toEqual({
+      text: `${header('sonic', '`sonic`')}and again`,
+      agents: ['sonic'],
+    });
+  });
+
+  test('a draft that is only mentions keeps the original text', () => {
+    // There is no request body to delegate, so rewriting it would lose the
+    // user's input; the agents list is still reported.
+    expect(translateAgentMentions('@sonic @architect', AGENTS)).toEqual({
+      text: '@sonic @architect',
+      agents: ['sonic', 'architect'],
+    });
+    expect(translateAgentMentions('  @sonic  ', AGENTS)).toEqual({ text: '  @sonic  ', agents: ['sonic'] });
+  });
+
+  test('the gap a removed mention leaves is closed, without reflowing the body', () => {
+    expect(translateAgentMentions('@sonic    do   it', AGENTS)).toEqual({
+      // The mention's OWN separator and its gap are collapsed…
+      text: `${header('sonic', '`sonic`')}do   it`,
+      agents: ['sonic'],
+    });
+    // …while the body's OWN spacing between other words is left alone. The old
+    // rule reflowed the whole body here (`do   it` → `do it`) and, on the same
+    // pass, dropped every blank line — `@architect\n\nx\n\n---\n\ny` came back
+    // with the divider directly under `x`, a setext H2 underline rather than a
+    // thematic break.
+    expect(translateAgentMentions('@sonic\n\nline\n\n---\n\ntail', AGENTS)).toEqual({
+      text: `${header('sonic', '`sonic`')}line\n\n---\n\ntail`,
+      agents: ['sonic'],
+    });
+  });
+
+  test('trailing punctuation stays in the body', () => {
+    expect(translateAgentMentions('@architect, please plan', AGENTS)).toEqual({
+      text: `${header('architect', '`architect`')}please plan`,
+      agents: ['architect'],
+    });
+  });
+
+  test('a quoted mention is translated like a bare one', () => {
+    expect(translateAgentMentions('@"architect" plan it', AGENTS)).toEqual({
+      text: `${header('architect', '`architect`')}plan it`,
+      agents: ['architect'],
+    });
+  });
+
+  test('the name casing the user typed is preserved in the header', () => {
+    expect(translateAgentMentions('@Archivist sort this', AGENTS)).toEqual({
+      text: `${header('Archivist', '`Archivist`')}sort this`,
+      agents: ['Archivist'],
+    });
+  });
+
+  test('a mid-token mention is not translated', () => {
+    expect(translateAgentMentions('email foo@architect now', AGENTS)).toEqual({
+      text: 'email foo@architect now',
+      agents: [],
+    });
+  });
+});

package/src/shared/lib/chat/composer/translate.ts

@@ -0,0 +1,149 @@
+export interface AgentMentionMatch {
+  name: string;
+  start: number;
+  end: number;
+}
+
+/** Picker-inserted `@file:` mentions (quoted form when the path has spaces). */
+const FILE_MENTION_QUOTED_RE = /(^|[\s([{])@"file:([^"]+)"/g;
+const FILE_MENTION_BARE_RE = /(^|[\s([{])@file:(\S+)/g;
+
+/**
+ * Rewrite picker-inserted `@file:<path>` / `@"file:<path with spaces>"`
+ * into oh-my-pi's native file-mention syntax `@<path>` / `@"<path>"`,
+ * which the omp runtime expands into attached file contents. The `file:`
+ * namespace means a file token can never collide with a bare `@agent`.
+ *
+ * NOTE: no trailing-punctuation stripping here — a path can legitimately end
+ * in `.`/`)` etc. (e.g. `foo.test.ts`), and the picker always inserts a
+ * trailing space anyway.
+ */
+export function translateFileMentions(text: string): string {
+  return text
+    .replace(FILE_MENTION_QUOTED_RE, '$1@"$2"')
+    .replace(FILE_MENTION_BARE_RE, '$1@$2');
+}
+
+/**
+ * `@` at string start or preceded by whitespace/`(`/`[`/`{`, followed by a
+ * quoted (`@"a b"` / `@'a b'`) or bare (`\S+`) token. A mention is only
+ * treated as an agent when the WHOLE token equals a known agent name, so a
+ * bare file path like `@build/x.ts` is never swallowed as agent `build`.
+ */
+const MENTION_RE = /(^|[\s([{])@("([^"]+)"|'([^']+)'|(\S+))/g;
+
+/** Trailing prose punctuation stripped from a bare token before name matching. */
+const TRAILING_PUNCT_RE = /[.,;:!?)\]}]+$/;
+
+/**
+ * Find every `@token` whose name matches a known agent. Returns each
+ * occurrence (duplicates included) with the span covering `@token`, so the
+ * caller can remove all of them; `translateAgentMentions` dedupes the names.
+ */
+export function extractAgentMentions(text: string, agentNames: readonly string[]): AgentMentionMatch[] {
+  const known = new Set(agentNames.map((name) => name.toLowerCase()));
+  const matches: AgentMentionMatch[] = [];
+
+  for (const m of text.matchAll(MENTION_RE)) {
+    const start = m.index + m[1].length;
+    const quoted = m[3] ?? m[4];
+
+    // Quoted tokens: name is the inner text verbatim; span covers `@` + quotes.
+    if (quoted !== undefined) {
+      if (!known.has(quoted.toLowerCase())) continue;
+      matches.push({ name: quoted, start, end: start + 1 + (m[2] ?? '').length });
+      continue;
+    }
+
+    // Bare tokens: strip trailing punctuation before comparing (e.g. `@architect.`).
+    const cleaned = (m[5] ?? '').replace(TRAILING_PUNCT_RE, '');
+    if (!known.has(cleaned.toLowerCase())) continue;
+    matches.push({ name: cleaned, start, end: start + 1 + cleaned.length });
+  }
+
+  return matches;
+}
+
+/**
+ * Close the gaps left by removed mentions without touching the body's own
+ * whitespace.
+ *
+ * The rule this replaced ran `[ \t]+ → ' '` and `\n{2,} → '\n'` over the WHOLE
+ * body, which is a markdown reflow: for `@architect\n\nDescribe it\n\n---\n\nDo
+ * X` the blank line before `---` disappeared, so the divider landed under the
+ * paragraph as a setext H2 underline instead of a thematic break, and the
+ * user's own paragraphs merged into one.
+ *
+ * A removal gap is the token, plus the run of spaces or tabs that followed it
+ * (the span already excludes the separator before it). Only the mention's OWN
+ * line is at stake: a mention that occupied its line takes that line's newline
+ * with it, while the whitespace the USER wrote between the body's own words is
+ * never touched — the old rule reflowed all of it, and dropped every blank line
+ * on the way.
+ */
+function collapseRemovedMentions(text: string, matches: readonly AgentMentionMatch[]): string {
+  let body = text;
+  let offset = 0;
+  for (const match of matches) {
+    const at = match.start - offset;
+    let end = at + 1;
+    while (end < body.length && !/\s/.test(body[end]!)) end += 1;
+
+    let lineStart = at;
+    while (lineStart > 0 && body[lineStart - 1] !== '\n') lineStart -= 1;
+    const onlyMentionOnLine =
+      body[lineStart] === '@'
+      && (end >= body.length || body[end] === '\n');
+
+    if (onlyMentionOnLine) {
+      // `^…@mention\n` — drop the line and the newline that terminated it.
+      const cutEnd = end < body.length ? end + 1 : end;
+      offset += cutEnd - lineStart;
+      body = body.slice(0, lineStart) + body.slice(cutEnd);
+      continue;
+    }
+
+    // Inline (or a mention followed by the user's own text on its line): the gap
+    // is the token plus the run of spaces after it. Collapsing exactly that much
+    // keeps `@a then @b go` from leaving a double space while stopping well
+    // short of the old whole-body reflow (the body's own `do   it` stays).
+    let gapEnd = end;
+    while (gapEnd < body.length && (body[gapEnd] === ' ' || body[gapEnd] === '\t')) gapEnd += 1;
+    offset += gapEnd - at;
+    body = body.slice(0, at) + body.slice(gapEnd);
+  }
+  return body.trim();
+}
+
+/**
+ * Rewrite `@agent` mentions into an explicit delegation directive the omp
+ * model acts on (oh-my-pi has no native `@agent` syntax). Pure and
+ * deterministic: no mentions leave the text untouched.
+ */
+export function translateAgentMentions(
+  text: string,
+  agentNames: readonly string[],
+): { text: string; agents: string[] } {
+  const matches = extractAgentMentions(text, agentNames);
+  if (matches.length === 0) return { text, agents: [] };
+
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const match of matches) {
+    const key = match.name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    names.push(match.name);
+  }
+
+  const body = collapseRemovedMentions(text, matches);
+
+  if (body === '') return { text, agents: names };
+
+  return {
+    text: `Use the task tool to delegate this request to the following oh-my-pi subagent(s): ${names
+      .map((n) => `\`${n}\``)
+      .join(', ')} (agent id: ${names.join(', ')}).\n\n${body}`,
+    agents: names,
+  };
+}

package/src/shared/lib/chat/composer/trigger.test.ts

@@ -0,0 +1,276 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * WHY: `detectComposerTrigger` decides when the popup opens and which span an
+ * accept overwrites; `insertToken` performs that overwrite. A wrong caret or
+ * `replaceFrom` mangles the user's draft — silently deleting prose or leaving
+ * half a command behind — so every case here pins the exact span, not just the
+ * kind. The mid-prompt rule matters too: a `/word` inside running prose must
+ * only ever surface skills, never the full command list.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import type { ComposerMatchItem, ComposerPickItem, ComposerTrigger } from '@/shared/types';
+import {
+  KABMO_COMMANDS,
+  detectComposerTrigger,
+  insertToken,
+  sendInsteadOfAccept,
+  tokenForItem,
+} from '@/shared/lib/chat/composer/trigger';
+
+function cmd(name: string): ComposerMatchItem {
+  return { id: `c-${name}`, name, description: '', kind: 'command', source: 'command', token: `/${name}`, match: null };
+}
+
+describe('detectComposerTrigger — command name phase', () => {
+  test('a leading slash at the caret opens the name phase', () => {
+    expect(detectComposerTrigger('/', 1)).toEqual({
+      kind: 'command',
+      query: '',
+      start: 0,
+      end: 1,
+      phase: 'name',
+      replaceFrom: 0,
+    });
+    expect(detectComposerTrigger('/fast', 5)).toEqual({
+      kind: 'command',
+      query: 'fast',
+      start: 0,
+      end: 5,
+      phase: 'name',
+      replaceFrom: 0,
+    });
+  });
+
+  test('the query is only what precedes the caret', () => {
+    const trigger = detectComposerTrigger('/fast', 3);
+    expect(trigger).toMatchObject({ query: 'fa', start: 0, end: 3, replaceFrom: 0 });
+  });
+
+  test('leading whitespace is skipped but the reported span stays absolute', () => {
+    expect(detectComposerTrigger('   /fa', 6)).toMatchObject({ query: 'fa', start: 3, replaceFrom: 3, end: 6 });
+  });
+
+  test('a slash inside a token never triggers', () => {
+    // `/tmp/fo` is a path, but it still starts with a slash, so the trigger
+    // fires and the popup simply filters to nothing.
+    expect(detectComposerTrigger('/tmp/fo', 7)).toMatchObject({ kind: 'command', query: 'tmp/fo' });
+    expect(detectComposerTrigger('a/b', 3)).toBeNull();
+  });
+
+  test('plain prose with no slash or at-sign triggers nothing', () => {
+    expect(detectComposerTrigger('hello world', 11)).toBeNull();
+    expect(detectComposerTrigger('', 0)).toBeNull();
+  });
+
+  test('a caret in the middle of the draft scopes detection to its own line', () => {
+    expect(detectComposerTrigger('one\ntwo', 7)).toBeNull();
+    expect(detectComposerTrigger('one\n/tw', 7)).toMatchObject({ query: 'tw', start: 4, end: 7 });
+  });
+});
+
+describe('detectComposerTrigger — args phase', () => {
+  test('a space after the command switches to args', () => {
+    expect(detectComposerTrigger('/fast ', 6)).toEqual({
+      kind: 'command',
+      query: '',
+      start: 0,
+      end: 6,
+      phase: 'args',
+      replaceFrom: 6,
+      command: 'fast',
+    });
+  });
+
+  test('the replacement is anchored on the argument text, keeping earlier arguments', () => {
+    const trigger = detectComposerTrigger('/security plan s', 16);
+    expect(trigger).toMatchObject({
+      kind: 'command',
+      phase: 'args',
+      command: 'security',
+      query: 'plan s',
+      start: 0,
+      end: 16,
+      replaceFrom: 10,
+    });
+  });
+
+  test('an argument typed before the caret is included in the query', () => {
+    expect(detectComposerTrigger('/fast on x', 10)).toMatchObject({ phase: 'args', query: 'on x', command: 'fast' });
+    expect(detectComposerTrigger('/fast on x', 8)).toMatchObject({ phase: 'args', query: 'on', command: 'fast' });
+  });
+
+  test('the command name is reported as typed', () => {
+    expect(detectComposerTrigger('/MODEL ', 7)).toMatchObject({ command: 'MODEL', phase: 'args' });
+  });
+
+  test('a leading-slash command with trailing prose is still args on its line', () => {
+    expect(detectComposerTrigger('/a b\n', 4)).toMatchObject({ phase: 'args', command: 'a', query: 'b' });
+  });
+});
+
+describe('detectComposerTrigger — mid-prompt', () => {
+  test('prose before the token on the same line marks it mid-prompt', () => {
+    expect(detectComposerTrigger('fix bug /han', 12)).toMatchObject({
+      kind: 'command',
+      phase: 'name',
+      query: 'han',
+      start: 8,
+      replaceFrom: 8,
+      midPrompt: true,
+    });
+  });
+
+  test('an earlier non-blank line marks a later line-start token mid-prompt', () => {
+    expect(detectComposerTrigger('prose\n/retry', 12)).toMatchObject({ midPrompt: true, query: 'retry', start: 6 });
+  });
+
+  test('a blank earlier line does not', () => {
+    expect(detectComposerTrigger('\n\n/retry', 8)).toMatchObject({ query: 'retry', start: 2 });
+    expect(detectComposerTrigger('\n\n/retry', 8)?.midPrompt).toBeUndefined();
+  });
+
+  test('indentation alone is not prose', () => {
+    expect(detectComposerTrigger('   /fa', 6)?.midPrompt).toBeUndefined();
+  });
+
+  test('a mid-prompt token never enters the args phase', () => {
+    // The trailing-slash rule only matches a slash token with no space after
+    // it, so once prose precedes `/fast o` there is no trigger at all: the
+    // popup closes rather than completing `fast`'s subcommands mid-prose.
+    expect(detectComposerTrigger('prose /fast o', 13)).toBeNull();
+    expect(detectComposerTrigger('prose /fast', 11)).toMatchObject({ phase: 'name', query: 'fast', midPrompt: true });
+  });
+});
+
+describe('detectComposerTrigger — @ mentions', () => {
+  test('an at-sign at index 0 opens a mention', () => {
+    expect(detectComposerTrigger('@sonic', 6)).toEqual({
+      kind: 'mention',
+      query: 'sonic',
+      start: 0,
+      end: 6,
+      phase: 'name',
+      replaceFrom: 0,
+    });
+  });
+
+  test('a preceding whitespace or opener bracket is allowed', () => {
+    expect(detectComposerTrigger('see @sonic', 10)).toMatchObject({ kind: 'mention', query: 'sonic', start: 4 });
+    expect(detectComposerTrigger('(@sonic', 7)).toMatchObject({ kind: 'mention', query: 'sonic', start: 1 });
+    expect(detectComposerTrigger('[@sonic', 7)).toMatchObject({ kind: 'mention', query: 'sonic', start: 1 });
+    expect(detectComposerTrigger('{@sonic', 7)).toMatchObject({ kind: 'mention', query: 'sonic', start: 1 });
+  });
+
+  test('a preceding ordinary character aborts the scan', () => {
+    expect(detectComposerTrigger('foo@bar', 7)).toBeNull();
+    expect(detectComposerTrigger('a@b', 3)).toBeNull();
+  });
+
+  test('the scan stops at whitespace between the at-sign and the caret', () => {
+    expect(detectComposerTrigger('@sonic x', 8)).toBeNull();
+    expect(detectComposerTrigger('@ sonic', 7)).toBeNull();
+  });
+
+  test('the mention query runs to the caret, not the end of the draft', () => {
+    expect(detectComposerTrigger('@son', 4)).toMatchObject({ query: 'son', start: 0, end: 4 });
+    expect(detectComposerTrigger('@file:src/a', 11)).toMatchObject({ query: 'file:src/a', start: 0, end: 11 });
+  });
+
+  test('the at-sign scan is scoped to the caret line', () => {
+    expect(detectComposerTrigger('x\n@son', 6)).toMatchObject({ kind: 'mention', query: 'son', start: 2 });
+  });
+
+  test('a caret clamped past the end uses the whole text', () => {
+    expect(detectComposerTrigger('@son', 99)).toMatchObject({ kind: 'mention', query: 'son', end: 4 });
+    expect(detectComposerTrigger('/fa', 99)).toMatchObject({ kind: 'command', query: 'fa', end: 3 });
+  });
+});
+
+describe('tokenForItem', () => {
+  const base: ComposerPickItem = {
+    id: 'x',
+    name: 'x',
+    description: '',
+    kind: 'command',
+    source: 'command',
+    token: '/x',
+  };
+
+  test('appends a trailing space by default', () => {
+    expect(tokenForItem(base)).toBe('/x ');
+  });
+
+  test('suppresses the space when the item asks to', () => {
+    expect(tokenForItem({ ...base, insertWithoutSpace: true })).toBe('/x');
+  });
+});
+
+describe('sendInsteadOfAccept', () => {
+  const trigger = (over: Partial<ComposerTrigger>): ComposerTrigger => ({
+    kind: 'command',
+    query: '',
+    start: 0,
+    end: 0,
+    phase: 'name',
+    replaceFrom: 0,
+    ...over,
+  });
+
+  test('a complete chamber-owned command lets Enter send', () => {
+    for (const command of KABMO_COMMANDS) {
+      const t = trigger({ query: command.name, phase: 'name' });
+      expect(sendInsteadOfAccept(t, cmd(command.name))).toBe(true);
+      expect(sendInsteadOfAccept(trigger({ query: command.name.toUpperCase() }), cmd(command.name))).toBe(true);
+    }
+  });
+
+  test('an incomplete Kabmo command still accepts', () => {
+    expect(sendInsteadOfAccept(trigger({ query: 'bt' }), cmd('btw'))).toBe(false);
+  });
+
+  test('a command omp owns always accepts, however complete', () => {
+    expect(sendInsteadOfAccept(trigger({ query: 'model' }), cmd('model'))).toBe(false);
+  });
+
+  test('nothing highlighted, args phase, or mention never sends', () => {
+    expect(sendInsteadOfAccept(trigger({ query: 'btw' }), undefined)).toBe(false);
+    expect(sendInsteadOfAccept(trigger({ query: 'btw', phase: 'args', command: 'btw' }), cmd('btw'))).toBe(false);
+    expect(sendInsteadOfAccept(trigger({ kind: 'mention', query: 'btw' }), cmd('btw'))).toBe(false);
+  });
+});
+
+describe('insertToken', () => {
+  test('splices the token over the name-phase span and lands the caret after it', () => {
+    const trigger = detectComposerTrigger('/fa', 3);
+    if (!trigger) throw new Error('expected a trigger');
+
+    expect(insertToken('/fa', trigger, '/fast ')).toEqual({ value: '/fast ', caret: 6 });
+  });
+
+  test('only the argument text is replaced in the args phase', () => {
+    const trigger = detectComposerTrigger('/security plan s', 16);
+    if (!trigger) throw new Error('expected a trigger');
+
+    expect(insertToken('/security plan s', trigger, 'scan')).toEqual({ value: '/security scan', caret: 14 });
+  });
+
+  test('text after the caret survives the splice', () => {
+    const trigger = detectComposerTrigger('/fa', 3);
+    if (!trigger) throw new Error('expected a trigger');
+
+    expect(insertToken('/fa rest', trigger, '/fast')).toEqual({ value: '/fast rest', caret: 5 });
+  });
+
+  test('a mention span is replaced exactly', () => {
+    const trigger = detectComposerTrigger('see @son', 8);
+    if (!trigger) throw new Error('expected a trigger');
+
+    expect(insertToken('see @son', trigger, '@sonic ')).toEqual({ value: 'see @sonic ', caret: 11 });
+  });
+});