@nebutra/agent-runtime 0.2.0

package/src/inbound-admission.test.ts

@@ -0,0 +1,394 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  admitInbound,
+  compileAllowlist,
+  hasMention,
+  InboundDebouncer,
+  type InboundLike,
+  matchesAllowlist,
+  requiresMention,
+  resolveSessionKey,
+} from "./inbound-admission.js";
+
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+
+function makeInbound(overrides: Partial<InboundLike> = {}): InboundLike {
+  return {
+    tenantId: "tenant-a",
+    channelId: "chan-1",
+    chatId: "chat-9",
+    senderId: "user-7",
+    text: "hello there",
+    receivedAt: "2026-05-17T10:00:00.000Z",
+    ...overrides,
+  };
+}
+
+// ── 1. resolveSessionKey ─────────────────────────────────────────────────────
+
+describe("resolveSessionKey", () => {
+  it("is deterministic for the same inputs", () => {
+    const inbound = makeInbound();
+    expect(resolveSessionKey(inbound)).toBe(resolveSessionKey(inbound));
+  });
+
+  it("is stable across object identity (re-created equal inputs)", () => {
+    const a = resolveSessionKey(makeInbound());
+    const b = resolveSessionKey(makeInbound());
+    expect(a).toBe(b);
+  });
+
+  it("never collides across tenants for otherwise-identical inputs", () => {
+    const t1 = resolveSessionKey(makeInbound({ tenantId: "tenant-a" }));
+    const t2 = resolveSessionKey(makeInbound({ tenantId: "tenant-b" }));
+    expect(t1).not.toBe(t2);
+  });
+
+  it("prefixes the key with the tenant id (cross-tenant isolation by construction)", () => {
+    const key = resolveSessionKey(makeInbound({ tenantId: "tenant-zed" }));
+    expect(key.startsWith("tenant-zed:")).toBe(true);
+  });
+
+  it("group default binding is per-chat: same chat different sender → same key", () => {
+    const a = resolveSessionKey(makeInbound({ senderId: "s1" }), { chatType: "group" });
+    const b = resolveSessionKey(makeInbound({ senderId: "s2" }), { chatType: "group" });
+    expect(a).toBe(b);
+  });
+
+  it("group binding per-sender: different sender → different key", () => {
+    const a = resolveSessionKey(makeInbound({ senderId: "s1" }), {
+      chatType: "group",
+      groupBinding: "per-sender",
+    });
+    const b = resolveSessionKey(makeInbound({ senderId: "s2" }), {
+      chatType: "group",
+      groupBinding: "per-sender",
+    });
+    expect(a).not.toBe(b);
+  });
+
+  it("group binding per-thread: different thread → different key, same thread → same", () => {
+    const a = resolveSessionKey(makeInbound({ threadId: "th-1" }), {
+      chatType: "group",
+      groupBinding: "per-thread",
+    });
+    const b = resolveSessionKey(makeInbound({ threadId: "th-2" }), {
+      chatType: "group",
+      groupBinding: "per-thread",
+    });
+    const c = resolveSessionKey(makeInbound({ threadId: "th-1" }), {
+      chatType: "group",
+      groupBinding: "per-thread",
+    });
+    expect(a).not.toBe(b);
+    expect(a).toBe(c);
+  });
+
+  it("DM default binding is per-sender: different sender → different key", () => {
+    const a = resolveSessionKey(makeInbound({ senderId: "s1" }), { chatType: "dm" });
+    const b = resolveSessionKey(makeInbound({ senderId: "s2" }), { chatType: "dm" });
+    expect(a).not.toBe(b);
+  });
+
+  it("DM per-chat override collapses senders to one key", () => {
+    const a = resolveSessionKey(makeInbound({ senderId: "s1" }), {
+      chatType: "dm",
+      groupBinding: "per-chat",
+    });
+    const b = resolveSessionKey(makeInbound({ senderId: "s2" }), {
+      chatType: "dm",
+      groupBinding: "per-chat",
+    });
+    expect(a).toBe(b);
+  });
+
+  it("does not mutate the inbound input", () => {
+    const inbound = makeInbound();
+    const snapshot = JSON.stringify(inbound);
+    resolveSessionKey(inbound, { chatType: "group" });
+    expect(JSON.stringify(inbound)).toBe(snapshot);
+  });
+
+  it("fails closed on empty tenant id", () => {
+    expect(() => resolveSessionKey(makeInbound({ tenantId: "" }))).toThrow();
+  });
+});
+
+// ── 2. compileAllowlist / matchesAllowlist ───────────────────────────────────
+
+describe("compileAllowlist / matchesAllowlist", () => {
+  it("exact id match is allowed and reports matchedBy", () => {
+    const compiled = compileAllowlist(["user-7", "user-8"]);
+    const res = matchesAllowlist(compiled, ["user-7"]);
+    expect(res.allowed).toBe(true);
+    expect(res.matchedBy).toBe("user-7");
+  });
+
+  it("denies when no candidate matches", () => {
+    const compiled = compileAllowlist(["user-7"]);
+    const res = matchesAllowlist(compiled, ["user-99"]);
+    expect(res.allowed).toBe(false);
+    expect(res.matchedBy).toBeUndefined();
+  });
+
+  it("whole-entry wildcard '*' allows any candidate", () => {
+    const compiled = compileAllowlist(["*"]);
+    expect(matchesAllowlist(compiled, ["anyone"]).allowed).toBe(true);
+  });
+
+  it("prefix wildcard 'prefix:*' matches by prefix", () => {
+    const compiled = compileAllowlist(["org-42:*"]);
+    expect(matchesAllowlist(compiled, ["org-42:user-1"]).allowed).toBe(true);
+    expect(matchesAllowlist(compiled, ["org-99:user-1"]).allowed).toBe(false);
+  });
+
+  it("prefix wildcard reports the matching entry", () => {
+    const compiled = compileAllowlist(["org-42:*"]);
+    expect(matchesAllowlist(compiled, ["org-42:user-1"]).matchedBy).toBe("org-42:*");
+  });
+
+  it("empty allowlist is closed by default (deny)", () => {
+    const compiled = compileAllowlist([]);
+    expect(matchesAllowlist(compiled, ["anyone"]).allowed).toBe(false);
+  });
+
+  it("empty allowlist with openWhenEmpty allows everything", () => {
+    const compiled = compileAllowlist([], { openWhenEmpty: true });
+    expect(matchesAllowlist(compiled, ["anyone"]).allowed).toBe(true);
+  });
+
+  it("openWhenEmpty does NOT open a non-empty allowlist", () => {
+    const compiled = compileAllowlist(["user-7"], { openWhenEmpty: true });
+    expect(matchesAllowlist(compiled, ["intruder"]).allowed).toBe(false);
+  });
+
+  it("checks multiple candidates and matches any", () => {
+    const compiled = compileAllowlist(["role:admin"]);
+    expect(matchesAllowlist(compiled, ["user-7", "role:admin"]).allowed).toBe(true);
+  });
+
+  it("does not mutate the entries array", () => {
+    const entries = ["a", "b:*"];
+    const snapshot = [...entries];
+    compileAllowlist(entries);
+    expect(entries).toEqual(snapshot);
+  });
+});
+
+// ── 3. requiresMention / hasMention ──────────────────────────────────────────
+
+describe("requiresMention / hasMention", () => {
+  it("DM never requires a mention", () => {
+    expect(requiresMention({ chatType: "dm", assistantHandles: ["@bot"], text: "hi" })).toBe(false);
+  });
+
+  it("group requires a mention when none present", () => {
+    expect(
+      requiresMention({ chatType: "group", assistantHandles: ["@bot"], text: "hello world" }),
+    ).toBe(true);
+  });
+
+  it("group does not require gating when message mentions the assistant", () => {
+    expect(
+      requiresMention({ chatType: "group", assistantHandles: ["@bot"], text: "hey @bot help" }),
+    ).toBe(false);
+  });
+
+  it("reply-to-assistant bypasses the mention requirement in group", () => {
+    expect(
+      requiresMention({
+        chatType: "group",
+        assistantHandles: ["@bot"],
+        text: "no mention here",
+        isReplyToAssistant: true,
+      }),
+    ).toBe(false);
+  });
+
+  it("hasMention is case-insensitive", () => {
+    expect(hasMention("Hey @BOT how are you", ["@bot"])).toBe(true);
+  });
+
+  it("hasMention matches on word boundaries (no substring false positive)", () => {
+    expect(hasMention("contact @botanist now", ["@bot"])).toBe(false);
+  });
+
+  it("hasMention is false when handle absent", () => {
+    expect(hasMention("nothing relevant", ["@bot"])).toBe(false);
+  });
+
+  it("hasMention supports multiple handles", () => {
+    expect(hasMention("ping @assistant please", ["@bot", "@assistant"])).toBe(true);
+  });
+});
+
+// ── 4. InboundDebouncer ──────────────────────────────────────────────────────
+
+describe("InboundDebouncer", () => {
+  it("does not admit a message while the window is open", () => {
+    const d = new InboundDebouncer();
+    expect(d.offer("sk", "first", 0)).toEqual({ admit: false });
+  });
+
+  it("coalesces a burst within the window and admits once on flush", () => {
+    const d = new InboundDebouncer({ windowMs: 1500 });
+    expect(d.offer("sk", "one", 0).admit).toBe(false);
+    expect(d.offer("sk", "two", 500).admit).toBe(false);
+    const flushed = d.flush("sk", 600);
+    expect(flushed).toEqual({ admit: true, merged: "one\ntwo" });
+  });
+
+  it("admits a coalesced burst once the window has closed via a later offer", () => {
+    const d = new InboundDebouncer({ windowMs: 1000 });
+    expect(d.offer("sk", "a", 0).admit).toBe(false);
+    expect(d.offer("sk", "b", 200).admit).toBe(false);
+    const res = d.offer("sk", "c", 2000);
+    expect(res).toEqual({ admit: true, merged: "a\nb" });
+  });
+
+  it("flush on an unknown sessionKey does not admit", () => {
+    const d = new InboundDebouncer();
+    expect(d.flush("never-seen", 1000)).toEqual({ admit: false });
+  });
+
+  it("treats distinct sessionKeys independently", () => {
+    const d = new InboundDebouncer({ windowMs: 1000 });
+    d.offer("sk-1", "x", 0);
+    d.offer("sk-2", "y", 0);
+    expect(d.flush("sk-1", 1100)).toEqual({ admit: true, merged: "x" });
+    expect(d.flush("sk-2", 1100)).toEqual({ admit: true, merged: "y" });
+  });
+
+  it("flush clears buffered state (second flush does not re-admit)", () => {
+    const d = new InboundDebouncer({ windowMs: 1000 });
+    d.offer("sk", "only", 0);
+    expect(d.flush("sk", 1100).admit).toBe(true);
+    expect(d.flush("sk", 1200)).toEqual({ admit: false });
+  });
+
+  it("starts a fresh window after a prior burst was flushed by a late offer", () => {
+    const d = new InboundDebouncer({ windowMs: 1000 });
+    d.offer("sk", "a", 0);
+    const first = d.offer("sk", "b", 5000);
+    expect(first).toEqual({ admit: true, merged: "a" });
+    // 'b' begins a new window — still pending until it closes.
+    expect(d.offer("sk", "c", 5200).admit).toBe(false);
+    expect(d.flush("sk", 6300)).toEqual({ admit: true, merged: "b\nc" });
+  });
+});
+
+// ── 5. admitInbound (compose) ────────────────────────────────────────────────
+
+describe("admitInbound", () => {
+  function basePolicy() {
+    return {
+      chatType: "group" as const,
+      allowlist: compileAllowlist(["user-7"]),
+      assistantHandles: ["@bot"],
+    };
+  }
+
+  it("fails closed when tenant id is empty", () => {
+    const d = new InboundDebouncer();
+    const res = admitInbound(makeInbound({ tenantId: "" }), basePolicy(), { debouncer: d });
+    expect(res).toEqual({ admit: false, reason: "empty-tenant" });
+  });
+
+  it("rejects a sender that is not allowlisted", () => {
+    const d = new InboundDebouncer();
+    const res = admitInbound(makeInbound({ senderId: "intruder", text: "@bot hi" }), basePolicy(), {
+      debouncer: d,
+    });
+    expect(res).toEqual({ admit: false, reason: "not-allowlisted" });
+  });
+
+  it("rejects a group message without a mention", () => {
+    const d = new InboundDebouncer();
+    const res = admitInbound(
+      makeInbound({ senderId: "user-7", text: "no mention" }),
+      basePolicy(),
+      { debouncer: d },
+    );
+    expect(res).toEqual({ admit: false, reason: "mention-required" });
+  });
+
+  it("debounces an admitted message until the window closes", () => {
+    const d = new InboundDebouncer({ windowMs: 1000 });
+    const res = admitInbound(
+      makeInbound({ senderId: "user-7", text: "@bot hello" }),
+      basePolicy(),
+      { debouncer: d, nowMs: 0 },
+    );
+    expect(res).toEqual({ admit: false, reason: "debounced" });
+  });
+
+  it("admits end-to-end once the debounce window closes", () => {
+    const d = new InboundDebouncer({ windowMs: 1000 });
+    const policy = basePolicy();
+    const i1 = makeInbound({ senderId: "user-7", text: "@bot one" });
+    expect(admitInbound(i1, policy, { debouncer: d, nowMs: 0 }).admit).toBe(false);
+    const i2 = makeInbound({ senderId: "user-7", text: "two" });
+    const res = admitInbound(i2, policy, { debouncer: d, nowMs: 5000 });
+    expect(res.admit).toBe(true);
+    if (res.admit) {
+      expect(res.text).toBe("@bot one");
+      expect(res.sessionKey.startsWith("tenant-a:")).toBe(true);
+    }
+  });
+
+  it("admits a DM without requiring a mention (still debounced first)", () => {
+    const d = new InboundDebouncer({ windowMs: 500 });
+    const policy = {
+      chatType: "dm" as const,
+      allowlist: compileAllowlist(["user-7"]),
+      assistantHandles: ["@bot"],
+    };
+    const i1 = makeInbound({ senderId: "user-7", text: "plain dm" });
+    const r0 = admitInbound(i1, policy, { debouncer: d, nowMs: 0 });
+    expect(r0.admit).toBe(false);
+    if (!r0.admit) expect(r0.reason).toBe("debounced");
+    const i2 = makeInbound({ senderId: "user-7", text: "later" });
+    const res = admitInbound(i2, policy, { debouncer: d, nowMs: 9000 });
+    expect(res.admit).toBe(true);
+    if (res.admit) expect(res.text).toBe("plain dm");
+  });
+
+  it("allowlist check precedes mention check (allowlist reason wins)", () => {
+    const d = new InboundDebouncer();
+    const res = admitInbound(
+      makeInbound({ senderId: "ghost", text: "no mention either" }),
+      basePolicy(),
+      { debouncer: d },
+    );
+    expect(res).toEqual({ admit: false, reason: "not-allowlisted" });
+  });
+
+  it("does not mutate the inbound input", () => {
+    const d = new InboundDebouncer();
+    const inbound = makeInbound({ senderId: "user-7", text: "@bot hi" });
+    const snapshot = JSON.stringify(inbound);
+    admitInbound(inbound, basePolicy(), { debouncer: d, nowMs: 0 });
+    expect(JSON.stringify(inbound)).toBe(snapshot);
+  });
+
+  it("reply-to-assistant bypasses mention gating in a group", () => {
+    const d = new InboundDebouncer({ windowMs: 100 });
+    const policy = basePolicy();
+    const i1 = makeInbound({ senderId: "user-7", text: "no mention but a reply" });
+    const r1 = admitInbound(i1, policy, {
+      debouncer: d,
+      nowMs: 0,
+      isReplyToAssistant: true,
+    });
+    expect(r1.admit).toBe(false);
+    if (!r1.admit) expect(r1.reason).toBe("debounced");
+    const i2 = makeInbound({ senderId: "user-7", text: "again" });
+    const r2 = admitInbound(i2, policy, {
+      debouncer: d,
+      nowMs: 9000,
+      isReplyToAssistant: true,
+    });
+    expect(r2.admit).toBe(true);
+  });
+});

package/src/inbound-admission.ts

@@ -0,0 +1,246 @@
+/**
+ * Inbound admission + conversation resolution (the multi-channel "front door").
+ *
+ * Faithful re-expression of a multi-channel assistant's pre-turn policy:
+ * resolve a stable tenant-scoped session key from a normalized inbound
+ * message, then gate it through allowlist → mention → debounce before it is
+ * allowed to become an agent turn. Pure data/logic; time is injected (no
+ * timers); tenant-scoped & fail-closed. No transport, no host I/O.
+ */
+
+import { z } from "zod";
+
+/** Minimal structural inbound shape (declared locally — no sibling imports). */
+export interface InboundLike {
+  readonly tenantId: string;
+  readonly channelId: string;
+  readonly chatId: string;
+  readonly threadId?: string | undefined;
+  readonly senderId: string;
+  readonly text: string;
+  readonly receivedAt: string;
+}
+
+export type ChatType = "dm" | "group";
+export type GroupBinding = "per-chat" | "per-sender" | "per-thread";
+
+export interface SessionKeyOptions {
+  readonly chatType?: ChatType | undefined;
+  readonly groupBinding?: GroupBinding | undefined;
+}
+
+const tenantSchema = z.string().min(1, "tenantId is required");
+
+/**
+ * Deterministic, tenant-prefixed conversation/session key. Cross-tenant keys
+ * can never collide (tenant is the first segment). Defaults: a group binds
+ * per-chat, a DM binds per-sender; an explicit `groupBinding` overrides.
+ */
+export function resolveSessionKey(inbound: InboundLike, opts: SessionKeyOptions = {}): string {
+  const tenantId = tenantSchema.parse(inbound.tenantId);
+  const chatType: ChatType = opts.chatType ?? "group";
+  const binding: GroupBinding =
+    opts.groupBinding ?? (chatType === "dm" ? "per-sender" : "per-chat");
+
+  const parts: string[] = [tenantId, inbound.channelId, inbound.chatId];
+  if (binding === "per-sender") parts.push(inbound.senderId);
+  else if (binding === "per-thread") parts.push(inbound.threadId ?? "");
+  return parts.join(":");
+}
+
+// ── Allowlist ────────────────────────────────────────────────────────────────
+
+export interface CompiledAllowlist {
+  readonly exact: ReadonlySet<string>;
+  readonly prefixes: ReadonlyArray<{ readonly prefix: string; readonly entry: string }>;
+  readonly matchAny: boolean;
+  readonly empty: boolean;
+  readonly openWhenEmpty: boolean;
+}
+
+export interface AllowlistMatch {
+  readonly allowed: boolean;
+  readonly matchedBy?: string | undefined;
+}
+
+export function compileAllowlist(
+  entries: ReadonlyArray<string>,
+  opts: { openWhenEmpty?: boolean } = {},
+): CompiledAllowlist {
+  const exact = new Set<string>();
+  const prefixes: { prefix: string; entry: string }[] = [];
+  let matchAny = false;
+  for (const raw of entries) {
+    const entry = raw.trim();
+    if (entry === "") continue;
+    if (entry === "*") {
+      matchAny = true;
+    } else if (entry.endsWith(":*")) {
+      prefixes.push({ prefix: entry.slice(0, -1), entry }); // keep through the ':'
+    } else {
+      exact.add(entry);
+    }
+  }
+  const empty = !matchAny && exact.size === 0 && prefixes.length === 0;
+  return {
+    exact,
+    prefixes,
+    matchAny,
+    empty,
+    openWhenEmpty: opts.openWhenEmpty === true,
+  };
+}
+
+export function matchesAllowlist(
+  compiled: CompiledAllowlist,
+  candidates: ReadonlyArray<string>,
+): AllowlistMatch {
+  if (compiled.empty) {
+    return compiled.openWhenEmpty ? { allowed: true } : { allowed: false };
+  }
+  if (compiled.matchAny) return { allowed: true, matchedBy: "*" };
+  for (const c of candidates) {
+    if (compiled.exact.has(c)) return { allowed: true, matchedBy: c };
+    const pre = compiled.prefixes.find((p) => c.startsWith(p.prefix));
+    if (pre) return { allowed: true, matchedBy: pre.entry };
+  }
+  return { allowed: false };
+}
+
+// ── Mention gating ───────────────────────────────────────────────────────────
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Case-insensitive, word-boundary-aware handle detection. */
+export function hasMention(text: string, handles: ReadonlyArray<string>): boolean {
+  return handles.some((h) => {
+    const handle = h.trim();
+    if (handle === "") return false;
+    // Not followed by a word char → `@bot` ≠ `@botanist`.
+    const re = new RegExp(`${escapeRegExp(handle)}(?!\\w)`, "i");
+    return re.test(text);
+  });
+}
+
+export interface MentionContext {
+  readonly chatType: ChatType;
+  readonly assistantHandles: ReadonlyArray<string>;
+  readonly text: string;
+  readonly isReplyToAssistant?: boolean | undefined;
+}
+
+/** A group message is gated unless it mentions the assistant or replies to it. */
+export function requiresMention(ctx: MentionContext): boolean {
+  if (ctx.chatType === "dm") return false;
+  if (ctx.isReplyToAssistant === true) return false;
+  return !hasMention(ctx.text, ctx.assistantHandles);
+}
+
+// ── Debounce ─────────────────────────────────────────────────────────────────
+
+export type DebounceResult = { admit: false } | { admit: true; merged: string };
+
+interface DebounceBuffer {
+  windowStart: number;
+  parts: string[];
+}
+
+/**
+ * Coalesces a burst per session key. Time is injected (`nowMs`). A later
+ * offer whose window has closed flushes (admits) the prior buffer and opens
+ * a fresh window for the new message. `flush` force-admits regardless of the
+ * window and clears state.
+ */
+export class InboundDebouncer {
+  readonly #windowMs: number;
+  readonly #buffers = new Map<string, DebounceBuffer>();
+
+  constructor(opts: { windowMs?: number } = {}) {
+    this.#windowMs = opts.windowMs ?? 1500;
+  }
+
+  offer(sessionKey: string, message: string, nowMs: number): DebounceResult {
+    const buf = this.#buffers.get(sessionKey);
+    if (!buf) {
+      this.#buffers.set(sessionKey, { windowStart: nowMs, parts: [message] });
+      return { admit: false };
+    }
+    if (nowMs - buf.windowStart >= this.#windowMs) {
+      const merged = buf.parts.join("\n");
+      this.#buffers.set(sessionKey, { windowStart: nowMs, parts: [message] });
+      return { admit: true, merged };
+    }
+    buf.parts.push(message);
+    return { admit: false };
+  }
+
+  flush(sessionKey: string, _nowMs: number): DebounceResult {
+    const buf = this.#buffers.get(sessionKey);
+    if (!buf) return { admit: false };
+    this.#buffers.delete(sessionKey);
+    return { admit: true, merged: buf.parts.join("\n") };
+  }
+}
+
+// ── Compose ──────────────────────────────────────────────────────────────────
+
+export interface AdmissionPolicy {
+  readonly chatType: ChatType;
+  readonly allowlist: CompiledAllowlist;
+  readonly assistantHandles: ReadonlyArray<string>;
+  readonly groupBinding?: GroupBinding | undefined;
+}
+
+export interface AdmissionDeps {
+  readonly debouncer: InboundDebouncer;
+  readonly nowMs?: number | undefined;
+  readonly isReplyToAssistant?: boolean | undefined;
+}
+
+export type AdmissionReason = "empty-tenant" | "not-allowlisted" | "mention-required" | "debounced";
+
+export type AdmissionResult =
+  | { readonly admit: true; readonly sessionKey: string; readonly text: string }
+  | { readonly admit: false; readonly reason: AdmissionReason };
+
+/**
+ * Pipeline: tenant → allowlist → session key → debounce → mention.
+ *
+ * A window-closing offer admits the PRIOR (already-gated) buffered content,
+ * so a message that itself lacks a mention can still flush the conversation.
+ * The current message's mention gate only governs whether it produces a
+ * `mention-required` vs `debounced` outcome while it waits.
+ */
+export function admitInbound(
+  inbound: InboundLike,
+  policy: AdmissionPolicy,
+  deps: AdmissionDeps,
+): AdmissionResult {
+  if (typeof inbound.tenantId !== "string" || inbound.tenantId.trim() === "") {
+    return { admit: false, reason: "empty-tenant" };
+  }
+
+  const allow = matchesAllowlist(policy.allowlist, [inbound.senderId]);
+  if (!allow.allowed) return { admit: false, reason: "not-allowlisted" };
+
+  const sessionKey = resolveSessionKey(inbound, {
+    chatType: policy.chatType,
+    groupBinding: policy.groupBinding,
+  });
+
+  const nowMs = deps.nowMs ?? Date.now();
+  const result = deps.debouncer.offer(sessionKey, inbound.text, nowMs);
+  if (result.admit) {
+    return { admit: true, sessionKey, text: result.merged };
+  }
+
+  const gated = requiresMention({
+    chatType: policy.chatType,
+    assistantHandles: policy.assistantHandles,
+    text: inbound.text,
+    isReplyToAssistant: deps.isReplyToAssistant,
+  });
+  return { admit: false, reason: gated ? "mention-required" : "debounced" };
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @nebutra/agent-runtime — multi-tenant agent-runtime grammar.
+ *
+ * A faithful re-expression of a terminal coding-agent's runtime *design*
+ * (thread/turn/item model, approval + capability policy, uniform tool/MCP
+ * abstraction, event-sourced rollout, external-sandbox delegation) into
+ * Sailor's grammar: TypeScript, multi-tenant, no infra changes, no in-process
+ * untrusted-code execution.
+ *
+ * Track A (this package): policy + protocol + model + rollout, all tenant-scoped.
+ * Track B (decoupled, not this repo): an optional isolator/kernel sidecar that
+ * implements {@link ExternalSandbox} over the ./protocol contract.
+ */
+
+export * from "./artifact-stream";
+export * from "./channel-gateway";
+export * from "./code-review";
+export * from "./command-suggestions";
+export * from "./commands";
+export * from "./commit-message";
+export * from "./context-compaction";
+export * from "./definitions";
+export * from "./deployment-status";
+export * from "./design-context";
+export * from "./dispatcher";
+export * from "./durable-turn";
+export * from "./edit-planner";
+export * from "./fuzzy-match";
+export * from "./hook-pipeline";
+export * from "./inbound-admission";
+export * from "./loop";
+export * from "./mcp-bridge";
+export * from "./memory-provider";
+export * from "./model";
+export * from "./permission-ruleset";
+export * from "./policy";
+export * from "./project-repo";
+export * from "./protocol";
+export * from "./rollout";
+export * from "./rollout-store-persistent";
+export * from "./sandbox";
+export * from "./session-share";
+export * from "./skill-distillation";
+export * from "./skills";
+export * from "./subagents";
+export * from "./tools";
+export * from "./workbench";