@frockbot/plugin-shell 0.0.0 → 0.1.0

package/src/client/model-presentation.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { modelRuntimeLabel } from "./model-presentation.js";
+
+describe("model runtime presentation", () => {
+  test("names the model and its provider Package", () => {
+    expect(
+      modelRuntimeLabel({
+        modelDisplayName: "Llama 3",
+        providerModelId: "llama-3:cloud",
+        packageDisplayName: "Ollama Cloud",
+        connectionDisplayName: "Work",
+        hasModel: true,
+      }),
+    ).toBe("Llama 3 · Ollama Cloud");
+    expect(
+      modelRuntimeLabel({
+        providerModelId: "llama-3:cloud",
+        connectionDisplayName: "Custom provider",
+        hasModel: true,
+      }),
+    ).toBe("llama-3:cloud · Custom provider");
+  });
+
+  test("reads the same whether the model is the Bot's or the User default", () => {
+    const label = {
+      modelDisplayName: "Llama 3",
+      packageDisplayName: "Ollama Cloud",
+      hasModel: true,
+    };
+    expect(modelRuntimeLabel(label)).toBe("Llama 3 · Ollama Cloud");
+    expect(modelRuntimeLabel({ ...label, hasModel: false })).toBe(
+      "No default model",
+    );
+  });
+});

package/src/client/model-presentation.ts

@@ -0,0 +1,19 @@
+/**
+ * The model line the shell shows above the composer. It names the model the
+ * Bot actually runs on, whether that model is the Bot's own override or the
+ * User's default: a Bot that "just works" does not advertise where its
+ * settings came from.
+ */
+export function modelRuntimeLabel(input: {
+  modelDisplayName?: string;
+  providerModelId?: string;
+  packageDisplayName?: string;
+  connectionDisplayName?: string;
+  hasModel: boolean;
+}): string {
+  if (!input.hasModel) return "No default model";
+  const model =
+    input.modelDisplayName ?? input.providerModelId ?? "Connected model";
+  const provider = input.packageDisplayName ?? input.connectionDisplayName;
+  return provider ? `${model} · ${provider}` : model;
+}

package/src/client/notify.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { showClientNotificationV1 } from "./notify.js";
+
+const globals = globalThis as unknown as {
+  window?: Record<string, unknown>;
+  Notification?: unknown;
+};
+const original = { window: globals.window, Notification: globals.Notification };
+
+afterEach(() => {
+  globals.window = original.window;
+  globals.Notification = original.Notification;
+});
+
+function shellBridge(commandId: string, calls: unknown[]) {
+  return {
+    list: () => [{ id: commandId }],
+    invoke: (request: unknown) => {
+      calls.push(request);
+      return Promise.resolve({ status: "ok" });
+    },
+  };
+}
+
+function webNotification(shown: unknown[]) {
+  class FakeNotification {
+    static permission = "granted";
+    constructor(title: string, options?: { body?: string }) {
+      shown.push({ title, body: options?.body });
+    }
+  }
+  return FakeNotification;
+}
+
+describe("the client notification seam", () => {
+  test("prefers the desktop Package when the shell exposes it", async () => {
+    const calls: unknown[] = [];
+    const shown: unknown[] = [];
+    globals.window = {
+      frockbotDesktop: shellBridge("desktop.notifications.show", calls),
+      Notification: webNotification(shown),
+    };
+    globals.Notification = globals.window.Notification;
+    expect(
+      await showClientNotificationV1({ title: "Alpha replied", body: "hi" }),
+    ).toBe("desktop");
+    expect(calls).toEqual([
+      {
+        schemaVersion: 1,
+        action: "invoke",
+        commandId: "desktop.notifications.show",
+        input: { title: "Alpha replied", body: "hi", urgency: "normal" },
+      },
+    ]);
+    expect(shown).toEqual([]);
+  });
+
+  test("uses the mobile Package when that is the shell", async () => {
+    const calls: unknown[] = [];
+    globals.window = {
+      // The desktop bridge exists but exposes no commands, exactly as the
+      // Electron preload does today.
+      frockbotDesktop: { request: () => Promise.resolve(undefined) },
+      frockbotMobile: shellBridge("mobile.notifications.show", calls),
+    };
+    globals.Notification = undefined;
+    expect(await showClientNotificationV1({ title: "Beta", body: "" })).toBe(
+      "mobile",
+    );
+    expect(calls).toHaveLength(1);
+  });
+
+  test("falls back to the web API, and reports when nothing can show it", async () => {
+    const shown: unknown[] = [];
+    const Notification = webNotification(shown);
+    globals.window = { Notification };
+    globals.Notification = Notification;
+    expect(await showClientNotificationV1({ title: "Gamma", body: "b" })).toBe(
+      "web",
+    );
+    expect(shown).toEqual([{ title: "Gamma", body: "b" }]);
+
+    Notification.permission = "denied";
+    expect(await showClientNotificationV1({ title: "Gamma", body: "b" })).toBe(
+      "unavailable",
+    );
+    expect(shown).toHaveLength(1);
+  });
+});

package/src/client/notify.ts

@@ -0,0 +1,101 @@
+/**
+ * The one place the hosted client raises a notification.
+ *
+ * Progressive enhancement, in the constitution's sense: when the shell around
+ * the WebUI exposes its notifications Package — `desktop.notifications.show`
+ * or `mobile.notifications.show` — the intent goes there, because the platform
+ * shows it the way the platform shows notifications. When it does not, the web
+ * `Notification` API carries it. Neither Package changes for this; the seam
+ * only asks what the host already exposes.
+ */
+
+/** What a shell exposes to the hosted page. Detected structurally. */
+interface HostedCapabilityBridge {
+  list(): readonly { id: string }[];
+  invoke(request: unknown, signal?: AbortSignal): Promise<{ status: string }>;
+}
+
+export interface ClientNotificationIntentV1 {
+  title: string;
+  body: string;
+  urgency?: "normal" | "critical";
+}
+
+export type ClientNotificationDeliveryV1 =
+  "desktop" | "mobile" | "web" | "unavailable";
+
+const DESKTOP_SHOW_COMMAND = "desktop.notifications.show";
+const MOBILE_SHOW_COMMAND = "mobile.notifications.show";
+
+function bridge(candidate: unknown): HostedCapabilityBridge | undefined {
+  if (typeof candidate !== "object" || candidate === null) return undefined;
+  const value = candidate as Partial<HostedCapabilityBridge>;
+  return typeof value.list === "function" && typeof value.invoke === "function"
+    ? (value as HostedCapabilityBridge)
+    : undefined;
+}
+
+function exposes(host: HostedCapabilityBridge, commandId: string): boolean {
+  try {
+    return host.list().some((command) => command.id === commandId);
+  } catch {
+    return false;
+  }
+}
+
+async function invokeShow(
+  host: HostedCapabilityBridge,
+  commandId: string,
+  intent: ClientNotificationIntentV1,
+): Promise<boolean> {
+  try {
+    const result = await host.invoke({
+      schemaVersion: 1,
+      action: "invoke",
+      commandId,
+      input: {
+        title: intent.title,
+        body: intent.body,
+        urgency: intent.urgency ?? "normal",
+      },
+    });
+    return result.status === "ok";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Shows one notification through the best surface available. Never throws: a
+ * notification that cannot be shown reports how far it got, and the caller
+ * decides what to say about it.
+ */
+export async function showClientNotificationV1(
+  intent: ClientNotificationIntentV1,
+): Promise<ClientNotificationDeliveryV1> {
+  const host = globalThis.window as unknown as
+    Record<string, unknown> | undefined;
+  if (host) {
+    const desktop = bridge(host.frockbotDesktop);
+    if (desktop && exposes(desktop, DESKTOP_SHOW_COMMAND)) {
+      if (await invokeShow(desktop, DESKTOP_SHOW_COMMAND, intent)) {
+        return "desktop";
+      }
+    }
+    const mobile = bridge(host.frockbotMobile);
+    if (mobile && exposes(mobile, MOBILE_SHOW_COMMAND)) {
+      if (await invokeShow(mobile, MOBILE_SHOW_COMMAND, intent)) {
+        return "mobile";
+      }
+    }
+  }
+  if (
+    typeof window === "undefined" ||
+    !("Notification" in window) ||
+    Notification.permission !== "granted"
+  ) {
+    return "unavailable";
+  }
+  new Notification(intent.title, { body: intent.body });
+  return "web";
+}

package/src/client/skill-invocation.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+import type { ClientSkillCatalogEntryV1 } from "../skill-protocol.js";
+import {
+  nextSkillHighlightV1,
+  rankSkillCandidatesV1,
+  SkillAttachmentStore,
+  skillPopoverForV1,
+  textWithoutSkillTriggerV1,
+} from "./skill-invocation.js";
+
+function entry(
+  slug: string,
+  name: string,
+  description = "Use this when something happens.",
+): ClientSkillCatalogEntryV1 {
+  return {
+    ref: `bot/${slug}`,
+    skill: { schemaVersion: 1, source: "bot", slug },
+    name,
+    description,
+    path: `skills/${slug}/SKILL.md`,
+  };
+}
+
+const catalog = [
+  entry("daily-standup", "Daily standup"),
+  entry("standup-notes", "Standup notes"),
+  entry("release", "Release", "Use this when cutting a release standup."),
+  entry("weekly-report", "Weekly report"),
+];
+
+describe("the popover's ranking", () => {
+  test("offers the whole catalog with no query", () => {
+    const ranked = rankSkillCandidatesV1(catalog, "");
+    expect(ranked).toHaveLength(4);
+    expect(ranked.every((candidate) => candidate.rank === 0)).toBe(true);
+  });
+
+  test("ranks an exact slug above a prefix, a prefix above a substring, and a name above a description", () => {
+    const ranked = rankSkillCandidatesV1(catalog, "standup");
+    expect(ranked.map((candidate) => candidate.entry.ref)).toEqual([
+      // exact slug is nothing here, so: prefix, then substring, then description
+      "bot/standup-notes",
+      "bot/daily-standup",
+      "bot/release",
+    ]);
+  });
+
+  test("matches case-insensitively and drops what does not match", () => {
+    const ranked = rankSkillCandidatesV1(catalog, "WEEKLY");
+    expect(ranked.map((candidate) => candidate.entry.ref)).toEqual([
+      "bot/weekly-report",
+    ]);
+  });
+
+  test("does not offer a Skill that is already attached", () => {
+    const ranked = rankSkillCandidatesV1(catalog, "standup", {
+      exclude: [{ schemaVersion: 1, source: "bot", slug: "standup-notes" }],
+    });
+    expect(ranked.map((candidate) => candidate.entry.ref)).not.toContain(
+      "bot/standup-notes",
+    );
+  });
+});
+
+describe("reading the popover out of the composer", () => {
+  test("opens on / and on @ at the start of the message", () => {
+    expect(skillPopoverForV1("/stand", 6)).toEqual({
+      trigger: "/",
+      at: 0,
+      query: "stand",
+    });
+    expect(skillPopoverForV1("@stand", 6)?.trigger).toBe("@");
+  });
+
+  test("opens after whitespace but not inside a word", () => {
+    expect(skillPopoverForV1("write up /stand", 15)?.query).toBe("stand");
+    // An email address or a path in prose is not a Skill picker.
+    expect(skillPopoverForV1("tim@futuredirectors", 19)).toBeUndefined();
+    expect(skillPopoverForV1("docs/architecture", 17)).toBeUndefined();
+  });
+
+  test("closes once whitespace follows the trigger", () => {
+    expect(skillPopoverForV1("/stand up", 9)).toBeUndefined();
+  });
+
+  test("removes the trigger and its query on selection, keeping the rest", () => {
+    const popover = skillPopoverForV1("morning /stand", 14)!;
+    expect(textWithoutSkillTriggerV1("morning /stand", popover, 14)).toEqual({
+      text: "morning ",
+      caret: 8,
+    });
+  });
+});
+
+describe("the attached refs", () => {
+  test("attaches up to three and refuses the fourth", () => {
+    const store = new SkillAttachmentStore();
+    expect(store.attach(catalog[0]!)).toBe(true);
+    expect(store.attach(catalog[1]!)).toBe(true);
+    expect(store.attach(catalog[2]!)).toBe(true);
+    expect(store.full()).toBe(true);
+    expect(store.attach(catalog[3]!)).toBe(false);
+    expect(store.refs()).toHaveLength(3);
+  });
+
+  test("refuses the same Skill twice", () => {
+    const store = new SkillAttachmentStore();
+    expect(store.attach(catalog[0]!)).toBe(true);
+    expect(store.attach(catalog[0]!)).toBe(false);
+  });
+
+  test("detaches by ref and hands the list over on submission", () => {
+    const store = new SkillAttachmentStore();
+    store.attach(catalog[0]!);
+    store.attach(catalog[1]!);
+    store.detach("bot/daily-standup");
+    expect(store.take()).toEqual([
+      { schemaVersion: 1, source: "bot", slug: "standup-notes" },
+    ]);
+    expect(store.attached()).toEqual([]);
+  });
+
+  test("gives the refs back when a submission is refused", () => {
+    const store = new SkillAttachmentStore();
+    store.attach(catalog[0]!);
+    const held = [...store.attached()];
+    store.take();
+    store.restore(held);
+    expect(store.refs()).toEqual([
+      { schemaVersion: 1, source: "bot", slug: "daily-standup" },
+    ]);
+  });
+});
+
+describe("keyboard navigation", () => {
+  test("wraps at both ends and stays at zero on an empty list", () => {
+    expect(nextSkillHighlightV1(0, 3, 1)).toBe(1);
+    expect(nextSkillHighlightV1(2, 3, 1)).toBe(0);
+    expect(nextSkillHighlightV1(0, 3, -1)).toBe(2);
+    expect(nextSkillHighlightV1(0, 0, 1)).toBe(0);
+  });
+});

package/src/client/skill-invocation.ts

@@ -0,0 +1,175 @@
+// The composer's Skill-invocation state, as a pure store.
+//
+// GrokBot's users invoke a Skill with `/` or `@`
+// (`docs/research/grokbot-computer.md` §2.8). Selecting one does *not* paste
+// its text into the message: it attaches a ref, and the backend expands the
+// body it resolves at the exact generation the Turn loads. That distinction is
+// the whole point — a pasted body is a message the User could edit into
+// something the Skill never said, while a ref is a name the Bot resolves.
+//
+// Everything here is framework-free so the ranking, the keyboard model and the
+// three-chip bound are testable without mounting a component. The Vue
+// component owns focus and rendering; it owns no rules.
+import {
+  formatSkillRefV1,
+  MAX_INVOKED_SKILLS_V1,
+  type SkillRefV1,
+} from "@frockbot/kernel-contracts";
+import type { ClientSkillCatalogEntryV1 } from "../skill-protocol.js";
+
+/** The characters that open the popover, in GrokBot's shape. */
+export const SKILL_TRIGGER_CHARACTERS_V1 = ["/", "@"] as const;
+
+/** The open popover: which trigger opened it, and what has been typed since. */
+export interface SkillPopoverStateV1 {
+  trigger: "/" | "@";
+  /** Index in the text where the trigger character sits. */
+  at: number;
+  query: string;
+}
+
+/** One ranked candidate the popover offers. */
+export interface SkillCandidateV1 {
+  entry: ClientSkillCatalogEntryV1;
+  /** Lower sorts first. Exposed so a test can assert the ordering's reason. */
+  rank: number;
+}
+
+function matchScore(entry: ClientSkillCatalogEntryV1, query: string): number {
+  // 0 is "no query": everything matches and the catalog's own order stands.
+  if (!query) return 0;
+  const needle = query.toLowerCase();
+  const slug = entry.skill.slug.toLowerCase();
+  const name = entry.name.toLowerCase();
+  const description = entry.description.toLowerCase();
+  if (slug === needle || name === needle) return 1;
+  if (slug.startsWith(needle) || name.startsWith(needle)) return 2;
+  if (slug.includes(needle) || name.includes(needle)) return 3;
+  if (description.includes(needle)) return 4;
+  return Number.POSITIVE_INFINITY;
+}
+
+/**
+ * The candidates a query offers, best first.
+ *
+ * Ties break on the canonical ref rather than on catalog order, so the list a
+ * User navigates with the arrow keys does not reshuffle when the backend
+ * happens to enumerate the instruction root in a different order.
+ */
+export function rankSkillCandidatesV1(
+  catalog: readonly ClientSkillCatalogEntryV1[],
+  query: string,
+  options: { exclude?: readonly SkillRefV1[] } = {},
+): SkillCandidateV1[] {
+  const excluded = new Set(
+    (options.exclude ?? []).map((ref) => formatSkillRefV1(ref)),
+  );
+  return catalog
+    .filter((entry) => !excluded.has(entry.ref))
+    .map((entry) => ({ entry, rank: matchScore(entry, query) }))
+    .filter((candidate) => Number.isFinite(candidate.rank))
+    .sort(
+      (left, right) =>
+        left.rank - right.rank || left.entry.ref.localeCompare(right.entry.ref),
+    );
+}
+
+/**
+ * Reads the open popover out of the composer's text and caret.
+ *
+ * A trigger opens the popover only at the start of the message or after
+ * whitespace, so an email address or a path in prose does not turn into a Skill
+ * picker, and any whitespace after the trigger closes it again.
+ */
+export function skillPopoverForV1(
+  text: string,
+  caret: number,
+): SkillPopoverStateV1 | undefined {
+  const position = Math.max(0, Math.min(caret, text.length));
+  for (let index = position - 1; index >= 0; index -= 1) {
+    const character = text[index] ?? "";
+    if (/\s/u.test(character)) return undefined;
+    if (character === "/" || character === "@") {
+      const before = index === 0 ? "" : (text[index - 1] ?? "");
+      if (before !== "" && !/\s/u.test(before)) return undefined;
+      return {
+        trigger: character,
+        at: index,
+        query: text.slice(index + 1, position),
+      };
+    }
+  }
+  return undefined;
+}
+
+/** The text after a selection: the trigger and its query are removed. */
+export function textWithoutSkillTriggerV1(
+  text: string,
+  popover: SkillPopoverStateV1,
+  caret: number,
+): { text: string; caret: number } {
+  const end = Math.max(popover.at, Math.min(caret, text.length));
+  return {
+    text: `${text.slice(0, popover.at)}${text.slice(end)}`,
+    caret: popover.at,
+  };
+}
+
+/**
+ * The attached refs, bounded and ordered.
+ *
+ * Deep and small: `attach`, `detach` and `take` are the only ways the list
+ * changes, so the composer can never submit more refs than the decoder admits
+ * and can never submit the same one twice.
+ */
+export class SkillAttachmentStore {
+  #attached: ClientSkillCatalogEntryV1[] = [];
+
+  attached(): readonly ClientSkillCatalogEntryV1[] {
+    return this.#attached;
+  }
+
+  refs(): SkillRefV1[] {
+    return this.#attached.map((entry) => entry.skill);
+  }
+
+  full(): boolean {
+    return this.#attached.length >= MAX_INVOKED_SKILLS_V1;
+  }
+
+  /** True when the entry was attached; false when it was full or a duplicate. */
+  attach(entry: ClientSkillCatalogEntryV1): boolean {
+    if (this.full()) return false;
+    if (this.#attached.some((existing) => existing.ref === entry.ref)) {
+      return false;
+    }
+    this.#attached = [...this.#attached, entry];
+    return true;
+  }
+
+  detach(ref: string): void {
+    this.#attached = this.#attached.filter((entry) => entry.ref !== ref);
+  }
+
+  /** Empties the store and hands back what it held, for one submission. */
+  take(): SkillRefV1[] {
+    const refs = this.refs();
+    this.#attached = [];
+    return refs;
+  }
+
+  /** Puts a rejected submission's refs back, so nothing is lost on failure. */
+  restore(entries: readonly ClientSkillCatalogEntryV1[]): void {
+    this.#attached = entries.slice(0, MAX_INVOKED_SKILLS_V1);
+  }
+}
+
+/** Moves the popover's highlight, wrapping at both ends. */
+export function nextSkillHighlightV1(
+  highlighted: number,
+  count: number,
+  direction: 1 | -1,
+): number {
+  if (count <= 0) return 0;
+  return (highlighted + direction + count) % count;
+}