@cueloop/client 0.1.0-alpha.9 → 0.1.0-alpha.91

package/src/serve.ts

@@ -1,6 +1,6 @@
 /**
- * SSH-served TUI (#22 share path): `cueloop serve` lets teammates join a
- * review session over plain ssh. Every SSH connection renders <App> in
+ * SSH-served TUI: `cueloop serve` lets teammates join a
+ * thread over plain ssh. Every SSH connection renders <App> in
  * observer mode (readOnly) against the same local daemon; the one writable
  * controller stays the local owner's own `cueloop` TUI.
  *
@@ -20,7 +20,38 @@ import React from "react";
 import { createRoot } from "@opentui/react";
 import { createServer } from "@opentui/ssh";
 import { cueloopHome } from "@cueloop/daemon";
+import { DaemonClient } from "@cueloop/daemon/client";
+import type { Artifact } from "@cueloop/schema";
 import { App } from "./App";
+import { snapshotWorkbench } from "./workbench-snapshot";
+
+/** OSC background query budget: brief so a terminal that never answers falls back to dark. */
+const THEME_QUERY_TIMEOUT_MS = 200;
+
+/**
+ * The frozen diff an observer reads for a served workbench thread: captured once at serve time, so a
+ * late local edit never shifts it. Undefined when nothing is served or the thread is not a workbench.
+ */
+async function captureFrozenArtifact(
+  home: string,
+  sessionId: string | undefined,
+): Promise<Artifact | undefined> {
+  if (sessionId === undefined) return undefined;
+
+  const probe = await DaemonClient.connect({ home, autostart: true });
+
+  try {
+    const thread = await probe.sessionGet(sessionId).catch(() => undefined);
+
+    if (thread === undefined) return undefined;
+
+    const snapshot = await snapshotWorkbench(thread, (root, vcs) => probe.repoDiff(root, vcs));
+
+    return snapshot === thread ? undefined : snapshot.artifact;
+  } finally {
+    probe.close();
+  }
+}
 
 export interface ServeOptions {
   /** TCP port for the SSH listener; 0 picks an ephemeral port. Default 2222. */
@@ -33,7 +64,7 @@ export interface ServeOptions {
   home?: string;
   /** Silence the @opentui/ssh startup banner (tests). Default true. */
   banner?: boolean;
-  onError?: (err: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 
 export interface ServeHandle {
@@ -44,25 +75,35 @@ export interface ServeHandle {
   close(): Promise<void>;
 }
 
-export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle> {
-  const home = opts.home ?? cueloopHome();
+export async function serveClient(options: ServeOptions = {}): Promise<ServeHandle> {
+  const home = options.home ?? cueloopHome();
   const sshDir = join(home, "ssh");
+
   mkdirSync(sshDir, { recursive: true, mode: 0o700 });
 
+  const servedArtifact = await captureFrozenArtifact(home, options.sessionId);
+
   const server = createServer({
     // password-less by design; see the trust model in the module comment
     auth: "open",
     hostKey: { path: join(sshDir, "host_key") },
-    startupBanner: opts.banner ?? true,
+    startupBanner: options.banner ?? true,
     idleTimeout: "2h",
-    onError: opts.onError,
-  }).serve((session) => {
+    onError: options.onError,
+  }).serve(async (session) => {
+    // the observer's terminal reports its own background, so a light-terminal
+    // watcher gets the readable variant too
+    const appearance =
+      (await session.renderer.waitForThemeMode(THEME_QUERY_TIMEOUT_MS).catch(() => null)) ?? "dark";
     const root = createRoot(session.renderer);
+
     root.render(
       React.createElement(App, {
         home,
-        sessionId: opts.sessionId,
+        sessionId: options.sessionId,
         readOnly: true,
+        appearance,
+        servedArtifact,
         // q disconnects only this observer, never the server
         onExit: () => session.end(),
       }),
@@ -70,6 +111,7 @@ export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle>
     session.onClose(() => root.unmount());
   });
 
-  const info = await server.listen(opts.port ?? 2222, opts.host ?? "127.0.0.1");
+  const info = await server.listen(options.port ?? 2222, options.host ?? "127.0.0.1");
+
   return { ...info, close: () => server.close() };
 }

package/src/share.ts

@@ -0,0 +1,237 @@
+/**
+ * Publish a thread as a share: pack it, stream it to the gateway's
+ * `share` user over SSH, and copy the returned `ssh p_…@host` line to the
+ * clipboard. The planner holds no key, so all this side does is upload; the
+ * gateway seals and stores. Used by both `cueloop share` and the in-TUI
+ * Share button, so the two share exactly the same path.
+ */
+
+import {
+  DEFAULT_SHARE_HOST,
+  DEFAULT_SHARE_PORT,
+  SHARE_UPLOAD_USER,
+  packSessionBlob,
+} from "@cueloop/daemon/share-blob";
+import {
+  removalEntries,
+  viewFollowing,
+  type Annotation,
+  type ShareAccess,
+  type Thread,
+} from "@cueloop/schema";
+import { ThreadRecordSchema } from "@cueloop/daemon/validate";
+import type { SharedMerge } from "@cueloop/daemon/client";
+import * as v from "valibot";
+import { copyToClipboard } from "./clipboard";
+
+export interface ShareTarget {
+  host?: string;
+  port?: number;
+}
+
+export interface ShareResult {
+  /** The one line to paste: `ssh p_xxxxxxxx@host`. */
+  line: string;
+  /** Whether the line made it onto the system clipboard. */
+  copied: boolean;
+}
+
+/** The `p_…` share id inside a `ssh p_…@host` line, or undefined. */
+export function shareIdFromLine(line: string): string | undefined {
+  return line.match(/^ssh (\S+)@/)?.[1];
+}
+
+/** The paste line for a share id: `ssh p_…@host`. Used to copy an existing link. */
+export function formatShareLine(shareId: string, target: ShareTarget = {}): string {
+  return `ssh ${shareId}@${target.host ?? DEFAULT_SHARE_HOST}`;
+}
+
+/** Upload the session to the gateway and copy the resulting ssh line. */
+export async function publishShare(
+  session: Thread,
+  target: ShareTarget = {},
+): Promise<ShareResult> {
+  const { stdout, stderr, code } = await runShareSsh(
+    "cueloop-share",
+    // the share follows one branch: collaborators see its path wherever the owner stands
+    packSessionBlob(viewFollowing(session)),
+    target,
+  );
+
+  if (code !== 0)
+    throw new Error(`gateway upload failed: ${stderr.trim() || `ssh exited ${code}`}`);
+  const line = stdout.trim();
+
+  if (!line.startsWith("ssh ")) throw new Error(`unexpected gateway reply: ${line || "(empty)"}`);
+  const copied = await copyToClipboard(line);
+
+  return { line, copied };
+}
+
+/**
+ * Pull a share's current session back from the gateway. The gateway lets only
+ * the fingerprint that uploaded it through, so collaborator notes reach the
+ * planner without exposing the master key.
+ */
+export async function pullShare(shareId: string, target: ShareTarget = {}): Promise<Thread> {
+  const { stdout, stderr, code } = await runShareSsh("cueloop-pull", Buffer.from(shareId), target);
+
+  if (code !== 0) throw new Error(`gateway pull failed: ${stderr.trim() || `ssh exited ${code}`}`);
+
+  return v.parse(ThreadRecordSchema, JSON.parse(stdout));
+}
+
+/** A share's collaborator notes: the ones a viewer authored (author stamped). */
+export function collaboratorAnnotations(session: Thread): Annotation[] {
+  return session.annotations.filter((annotation) => annotation.author);
+}
+
+/**
+ * What a pulled share hands the local merge: collaborators' notes, the
+ * participant registry, and the removals the share recorded, by entry id.
+ */
+export function mergeFromShare(remote: Thread): SharedMerge {
+  const merge: SharedMerge = { annotations: collaboratorAnnotations(remote) };
+
+  if (remote.participants) merge.participants = remote.participants;
+  if (remote.history) {
+    merge.removals = removalEntries(remote.history).map((entry) => ({
+      id: entry.id,
+      annotationId: entry.annotationId,
+      createdAt: entry.createdAt,
+    }));
+  }
+
+  return merge;
+}
+
+/**
+ * Mirror the planner's own annotations up into the share, so collaborators see
+ * them on their next refresh. Owner-gated at the gateway; the notes stay
+ * unauthored (the planner's), unioned by id.
+ */
+export async function pushShare(
+  shareId: string,
+  annotations: Array<Omit<Annotation, "createdAt">>,
+  // ShareAccess sets a private allowlist; "public" clears it (makes the link public); undefined leaves it
+  access?: ShareAccess | "public",
+  target: ShareTarget = {},
+): Promise<void> {
+  const payload = access ? { shareId, annotations, access } : { shareId, annotations };
+  const { stderr, code } = await runShareSsh(
+    "cueloop-push",
+    Buffer.from(JSON.stringify(payload)),
+    target,
+  );
+
+  if (code !== 0) throw new Error(`gateway push failed: ${stderr.trim() || `ssh exited ${code}`}`);
+}
+
+/** Revoke a share: the gateway deletes the blob so its link stops resolving. Owner-gated; idempotent. */
+export async function revokeShare(shareId: string, target: ShareTarget = {}): Promise<void> {
+  const { stderr, code } = await runShareSsh("cueloop-revoke", Buffer.from(shareId), target);
+
+  if (code !== 0)
+    throw new Error(`gateway revoke failed: ${stderr.trim() || `ssh exited ${code}`}`);
+}
+
+export interface ShareWatchHandlers {
+  /** The whole session record, each time the share changes. */
+  onSession: (session: Thread) => void;
+  /** The stream ended, for any reason; the caller decides whether to reconnect. */
+  onClose: (reason: string) => void;
+}
+
+const WatchFrameSchema = v.variant("type", [
+  v.object({ type: v.literal("ready") }),
+  v.object({ type: v.literal("ping") }),
+  v.object({ type: v.literal("session"), session: ThreadRecordSchema }),
+]);
+
+/**
+ * Follow a share live: one long-lived `cueloop-watch` ssh stream that carries
+ * a JSON line per change. Owner-gated at the gateway. Returns a stop handle.
+ */
+export function watchShare(
+  shareId: string,
+  handlers: ShareWatchHandlers,
+  target: ShareTarget = {},
+): () => void {
+  const proc = Bun.spawn(shareSshCommand("cueloop-watch", target), {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  proc.stdin.write(shareId);
+  proc.stdin.end();
+  void readLines(proc.stdout, (line) => {
+    const frame = v.safeParse(WatchFrameSchema, JSON.parse(line));
+
+    if (frame.success && frame.output.type === "session") handlers.onSession(frame.output.session);
+  }).catch(() => {});
+  void Promise.all([proc.exited, new Response(proc.stderr).text()]).then(([code, stderr]) =>
+    handlers.onClose(stderr.trim() || `ssh exited ${code}`),
+  );
+
+  return () => proc.kill();
+}
+
+/** Feed each complete line of a byte stream to `onLine`; a torn line is dropped. */
+async function readLines(
+  stream: ReadableStream<Uint8Array>,
+  onLine: (line: string) => void,
+): Promise<void> {
+  const decoder = new TextDecoder();
+  let pending = "";
+
+  for await (const chunk of stream) {
+    pending += decoder.decode(chunk, { stream: true });
+    const lines = pending.split("\n");
+
+    pending = lines.pop() ?? "";
+    for (const line of lines) {
+      if (line.trim() === "") continue;
+      try {
+        onLine(line);
+      } catch {
+        // one bad line never ends the stream
+      }
+    }
+  }
+}
+
+function shareSshCommand(command: string, target: ShareTarget): string[] {
+  const host = target.host ?? DEFAULT_SHARE_HOST;
+  const port = target.port ?? DEFAULT_SHARE_PORT;
+
+  return [
+    "ssh",
+    "-p",
+    String(port),
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    `${SHARE_UPLOAD_USER}@${host}`,
+    command,
+  ];
+}
+
+/** Run one `share@host:port` ssh command with `stdin`; hand back its streams and exit code. */
+async function runShareSsh(
+  command: string,
+  stdin: Buffer,
+  target: ShareTarget,
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  const proc = Bun.spawn(shareSshCommand(command, target), {
+    stdin,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { stdout, stderr, code };
+}

package/src/skills.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadSkills } from "./skills";
+import { mergeSlashItems, type SlashItem } from "./slash-palette";
+
+function skillDir(): string {
+  const root = mkdtempSync(join(tmpdir(), "cueloop-skills-"));
+
+  mkdirSync(join(root, "typescript-magician"));
+  writeFileSync(
+    join(root, "typescript-magician", "SKILL.md"),
+    "---\nname: typescript-magician\ndescription: Design complex generic types.\n---\n\nbody\n",
+  );
+  mkdirSync(join(root, "no-frontmatter"));
+  writeFileSync(join(root, "no-frontmatter", "SKILL.md"), "just prose, no frontmatter\n");
+
+  return root;
+}
+
+describe("loadSkills", () => {
+  test("reads name and description from each SKILL.md frontmatter", () => {
+    const root = skillDir();
+
+    try {
+      const skills = loadSkills(root);
+      const magician = skills.find((skill) => skill.name === "typescript-magician");
+
+      expect(magician?.description).toBe("Design complex generic types.");
+      // a directory whose SKILL.md has no frontmatter is skipped, not crashed on
+      expect(skills.some((skill) => skill.name === "no-frontmatter")).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("a missing skills directory yields no skills", () => {
+    expect(loadSkills(join(tmpdir(), "cueloop-does-not-exist-xyz"))).toEqual([]);
+  });
+
+  test("CRLF delimiters parse, and a quoted name is unquoted", () => {
+    const root = mkdtempSync(join(tmpdir(), "cueloop-skills-crlf-"));
+
+    try {
+      mkdirSync(join(root, "review"));
+      writeFileSync(
+        join(root, "review", "SKILL.md"),
+        '---\r\nname: "review"\r\ndescription: Review the change.\r\n---\r\n',
+      );
+      const skills = loadSkills(root);
+
+      // no stray quotes and no CRLF-broken frontmatter
+      expect(skills.map((skill) => skill.name)).toEqual(["review"]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("mergeSlashItems", () => {
+  test("a quick action wins a name collision with a skill", () => {
+    const actions: SlashItem[] = [{ name: "lgtm", description: "action", body: "LGTM" }];
+    const skills: SlashItem[] = [
+      { name: "lgtm", description: "skill", body: "" },
+      { name: "vitest-patterns", description: "skill", body: "" },
+    ];
+    const merged = mergeSlashItems(actions, skills);
+
+    expect(merged.filter((item) => item.name === "lgtm")).toHaveLength(1);
+    expect(merged.find((item) => item.name === "lgtm")?.description).toBe("action");
+    expect(merged.some((item) => item.name === "vitest-patterns")).toBe(true);
+  });
+});

package/src/skills.ts

@@ -0,0 +1,75 @@
+import { createContext } from "react";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import * as v from "valibot";
+import type { SlashItem } from "./slash-palette";
+
+/** The default user-level skill store, harness-agnostic; a config path overrides it. */
+export function defaultSkillsDir(): string {
+  return join(homedir(), ".agents", "skills");
+}
+
+const SkillNameSchema = v.pipe(v.string(), v.trim(), v.minLength(1));
+
+/** One `key: value` line from the frontmatter, unquoted; undefined when the key is absent. */
+function frontmatterValue(frontmatter: string, key: string): string | undefined {
+  const match = new RegExp(`^${key}:\\s*(.+)$`, "m").exec(frontmatter);
+
+  return match
+    ? match[1]!
+        .trim()
+        .replace(/^["']|["']$/g, "")
+        .trim()
+    : undefined;
+}
+
+/** User skills as palette items: each `<dir>/SKILL.md` whose frontmatter carries a name and description. */
+export function loadSkills(dir: string): SlashItem[] {
+  let entries;
+
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const items: SlashItem[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let text;
+
+    try {
+      text = readFileSync(join(dir, entry.name, "SKILL.md"), "utf8");
+    } catch {
+      continue;
+    }
+    const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text.replace(/\r\n/g, "\n"));
+
+    if (!frontmatter) continue;
+    const name = v.safeParse(
+      SkillNameSchema,
+      frontmatterValue(frontmatter[1]!, "name") ?? entry.name,
+    );
+
+    if (!name.success) continue;
+
+    items.push({
+      name: name.output,
+      description: frontmatterValue(frontmatter[1]!, "description") ?? "",
+      body: "",
+    });
+  }
+
+  return items;
+}
+
+/** Skills reach the composer palette through context, so no surface needs a new prop to list them. */
+export const SlashSkillsContext = createContext<SlashItem[]>([]);
+
+/**
+ * The action and skill names every composer paints as "/name" references. Held in
+ * context so each surface - the plan thread, the diff sheet, the prototype - reads
+ * the same palette without threading a prop.
+ */
+export const PaletteNamesContext = createContext<ReadonlySet<string>>(new Set());

package/src/slash-palette.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import {
+  activeSlashToken,
+  insertSlashItem,
+  isStandaloneSlashQuery,
+  scoreMatch,
+  slashFilter,
+  type SlashItem,
+} from "./slash-palette";
+
+function item(name: string): SlashItem {
+  return { name, description: name, body: name };
+}
+
+const ITEMS: SlashItem[] = [
+  item("zoom-out-research-in-depth"),
+  item("restate-simplified"),
+  item("out-of-scope"),
+  item("lgtm"),
+];
+
+describe("scoreMatch", () => {
+  test("an exact name scores highest, then a prefix, then a subsequence", () => {
+    const exact = scoreMatch("lgtm", "lgtm")!;
+    const prefix = scoreMatch("lgtm-please", "lgtm")!;
+    const subsequence = scoreMatch("looking-good-to-me", "lgtm")!;
+
+    expect(exact).toBeGreaterThan(prefix);
+    expect(prefix).toBeGreaterThan(subsequence);
+  });
+
+  test("a query whose characters are not all present, in order, does not match", () => {
+    expect(scoreMatch("restate", "zzz")).toBeNull();
+    expect(scoreMatch("abc", "acb")).toBeNull();
+  });
+
+  test("an empty query matches everything", () => {
+    expect(scoreMatch("anything", "")).toBe(0);
+  });
+});
+
+describe("slashFilter", () => {
+  test("ranks a prefix match above a mere subsequence match", () => {
+    const ranked = slashFilter(ITEMS, "out");
+
+    expect(ranked[0]!.name).toBe("out-of-scope");
+    expect(ranked.map((entry) => entry.name)).toContain("zoom-out-research-in-depth");
+  });
+
+  test("drops items that do not match and returns all on an empty query", () => {
+    expect(slashFilter(ITEMS, "zzzz")).toEqual([]);
+    expect(slashFilter(ITEMS, "")).toHaveLength(ITEMS.length);
+  });
+});
+
+describe("activeSlashToken", () => {
+  const atEnd = (text: string) => activeSlashToken(text, text.length);
+
+  test("finds the caret's /word at the start or after a space, so each new / reopens the palette", () => {
+    expect(atEnd("/vitest-patt")).toBe("/vitest-patt");
+    expect(atEnd("use /vitest-patt")).toBe("/vitest-patt");
+    expect(atEnd("/zoom-out hello world /")).toBe("/");
+    // an underscore is a valid skill-name character, so the token spans it
+    expect(atEnd("run /my_skill")).toBe("/my_skill");
+  });
+
+  test("closes on the space that ends the token, and ignores prose", () => {
+    expect(atEnd("/zoom-out ")).toBeNull();
+    expect(atEnd("just some prose")).toBeNull();
+  });
+
+  test("tracks the caret, not the string end: a slash mid-draft is the active token", () => {
+    // caret sits right after "/imp" in "/imp done", ignoring the trailing text
+    expect(activeSlashToken("/imp done", 4)).toBe("/imp");
+    // caret inside plain prose, even with a later slash token, has no active token
+    expect(activeSlashToken("plain text /later", 5)).toBeNull();
+  });
+});
+
+describe("isStandaloneSlashQuery", () => {
+  test("true only when the whole draft is a bare /query, so prose ending in /name still saves", () => {
+    expect(isStandaloneSlashQuery("/lgtm")).toBe(true);
+    expect(isStandaloneSlashQuery("  /lgtm  ")).toBe(true);
+    expect(isStandaloneSlashQuery("please inspect /tmp")).toBe(false);
+    expect(isStandaloneSlashQuery("just prose")).toBe(false);
+  });
+});
+
+describe("insertSlashItem", () => {
+  test("replaces the active slash token with the reference and lands the caret after it", () => {
+    const result = insertSlashItem("look at /rev", 12, "review");
+
+    expect(result.text).toBe("look at /review ");
+    expect(result.caret).toBe("look at /review ".length);
+  });
+
+  test("keeps text after the caret intact", () => {
+    const result = insertSlashItem("/pl tail", 3, "plan");
+
+    expect(result.text).toBe("/plan  tail");
+    expect(result.caret).toBe("/plan ".length);
+  });
+});