@cueloop/client 0.1.0-alpha.0 → 0.1.0-alpha.100

package/src/integrations/pasted-image.ts

@@ -0,0 +1,60 @@
+/** Detects an image or other binary paste so a composer shows an [Image #n] placeholder instead of dumping raw bytes into the draft. */
+
+const IMAGE_MAGIC_SIGNATURES: number[][] = [
+  [0x89, 0x50, 0x4e, 0x47], // PNG
+  [0xff, 0xd8, 0xff], // JPEG
+  [0x47, 0x49, 0x46, 0x38], // GIF87a / GIF89a
+];
+
+const CONTROL_RATIO_THRESHOLD = 0.15;
+const PASTE_DECODER = new TextDecoder("utf-8", { fatal: false });
+
+function hasImageMagic(bytes: Uint8Array): boolean {
+  for (const signature of IMAGE_MAGIC_SIGNATURES) {
+    if (signature.every((byte, index) => bytes[index] === byte)) return true;
+  }
+
+  const isRiffWebp =
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 && // R
+    bytes[1] === 0x49 && // I
+    bytes[2] === 0x46 && // F
+    bytes[3] === 0x46 && // F
+    bytes[8] === 0x57 && // W
+    bytes[9] === 0x45 && // E
+    bytes[10] === 0x42 && // B
+    bytes[11] === 0x50; // P
+
+  return isRiffWebp;
+}
+
+function isControlCodePoint(codePoint: number): boolean {
+  if (codePoint === 0x09 || codePoint === 0x0a || codePoint === 0x0d) return false;
+
+  return codePoint < 0x20 || codePoint === 0x7f;
+}
+
+/** True when a paste is an image or other non-text binary payload and should collapse to a placeholder. */
+export function looksLikeBinaryPaste(bytes: Uint8Array): boolean {
+  if (bytes.length === 0) return false;
+  if (hasImageMagic(bytes)) return true;
+
+  const decoded = PASTE_DECODER.decode(bytes);
+  let controlCount = 0;
+  let total = 0;
+
+  for (const character of decoded) {
+    total += 1;
+    const codePoint = character.codePointAt(0) ?? 0;
+
+    if (codePoint === 0 || codePoint === 0xfffd) return true;
+    if (isControlCodePoint(codePoint)) controlCount += 1;
+  }
+
+  return total > 0 && controlCount / total > CONTROL_RATIO_THRESHOLD;
+}
+
+/** The draft placeholder for the nth image pasted into a composer: [Image #1], [Image #2], … */
+export function imagePlaceholder(index: number): string {
+  return `[Image #${index}]`;
+}

package/src/integrations/share.ts

@@ -0,0 +1,238 @@
+/**
+ * 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,
+  sharePublicationView,
+  type Annotation,
+  type SharePolicy,
+  type ShareLink,
+  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 {
+  line: string;
+  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 = {},
+  publication: SharePolicy & Pick<ShareLink, "shareBranch"> = {
+    requireAuth: false,
+    allowlist: [],
+  },
+): Promise<ShareResult> {
+  const { stdout, stderr, code } = await runShareSsh(
+    "cueloop-share",
+    packSessionBlob(sharePublicationView(session, publication)),
+    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.shares?.length === 1) merge.shareId = remote.shares[0]!.id;
+
+  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">>,
+  policy?: SharePolicy,
+  target: ShareTarget = {},
+): Promise<void> {
+  const payload = policy ? { shareId, annotations, policy } : { 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 {
+  onSession: (session: Thread) => void;
+  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/keyboard/components/CompletionOverlay.stories.tsx

@@ -0,0 +1,37 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { CompletionOverlay } from "./CompletionOverlay";
+
+export const meta: StoryMeta = { title: "Overlays/CompletionOverlay" };
+
+const noop = () => {};
+
+export const ApprovedPrompt: Story = {
+  render: () => (
+    <CompletionOverlay
+      message="approved"
+      completion={{ phase: "prompt" }}
+      status=""
+      onClose={noop}
+      onBackToPlan={noop}
+      onAlways={noop}
+    />
+  ),
+  expectedColors: [DARK.green],
+};
+
+export const FeedbackCounting: Story = {
+  render: () => (
+    <CompletionOverlay
+      message="changes_requested"
+      completion={{ phase: "counting", remaining: 3 }}
+      status="exported to vault/cueloop/plan.md"
+      returnsTo="agent/worker-3"
+      onClose={noop}
+      onBackToPlan={noop}
+      onAlways={noop}
+    />
+  ),
+  expectedColors: [DARK.accent],
+};

package/src/keyboard/components/CompletionOverlay.tsx

@@ -0,0 +1,75 @@
+/**
+ * Post-submit hand-back overlay: the agent is unblocked, the reviewer either
+ * closes now, opts into auto-close, or dismisses back to the resolved view.
+ * The latest status line (e.g. the vault-export path) stays visible here.
+ */
+
+import React from "react";
+import type { MessageOutcome } from "@cueloop/schema";
+import type { Theme } from "../../appearance/theme";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+import { Toolbar } from "../../ui/components/primitives/Toolbar";
+import { Button } from "../../ui/components/primitives/Button";
+
+export interface CompletionOverlayProps {
+  message: MessageOutcome;
+  completion: { phase: "prompt" } | { phase: "counting"; remaining: number };
+  status: string;
+  returnsTo?: string;
+  onClose: () => void;
+  onBackToPlan: () => void;
+  onAlways: () => void;
+  theme?: Theme;
+}
+
+export function CompletionOverlay({
+  message,
+  completion,
+  status,
+  returnsTo,
+  onClose,
+  onBackToPlan,
+  onAlways,
+  theme,
+}: CompletionOverlayProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const approved = message === "approved";
+
+  return (
+    <box
+      style={{
+        width: "100%",
+        height: "100%",
+        backgroundColor: tokens.background,
+        flexDirection: "column",
+        justifyContent: "center",
+        alignItems: "center",
+      }}
+    >
+      <text fg={approved ? tokens.green : tokens.accent}>
+        {approved ? "review approved" : "feedback sent"}
+      </text>
+      <text> </text>
+      <text fg={tokens.text}>
+        The agent has your {approved ? "approval" : "feedback"} and is unblocked.
+      </text>
+      {returnsTo ? <text fg={tokens.textDim}>returning to {returnsTo} on close</text> : null}
+      {status ? <text fg={tokens.textDim}>{status}</text> : null}
+      {completion.phase === "counting" ? (
+        <text fg={tokens.textDim}>closing in {completion.remaining}s</text>
+      ) : null}
+      <text> </text>
+      <Toolbar>
+        <Button variant="solid" marginRight={2} onPress={onClose} theme={theme}>
+          {" close "}
+        </Button>
+        <Button marginRight={2} onPress={onBackToPlan} theme={theme}>
+          {" back to plan "}
+        </Button>
+        <Button onPress={onAlways} theme={theme}>
+          {" always "}
+        </Button>
+      </Toolbar>
+    </box>
+  );
+}

package/src/keyboard/components/HandleChipsInput.stories.tsx

@@ -0,0 +1,24 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { HandleChipsInput } from "./HandleChipsInput";
+
+export const meta: StoryMeta = { title: "Inputs/HandleChips" };
+
+export const WithHandles: Story = {
+  render: () => (
+    <box style={{ padding: 1, backgroundColor: DARK.elevated }}>
+      <HandleChipsInput logins={["octocat", "hubot"]} onChange={() => {}} theme={DARK} />
+    </box>
+  ),
+  size: { width: 48, height: 6 },
+};
+
+export const Empty: Story = {
+  render: () => (
+    <box style={{ padding: 1, backgroundColor: DARK.elevated }}>
+      <HandleChipsInput logins={[]} onChange={() => {}} theme={DARK} />
+    </box>
+  ),
+  size: { width: 48, height: 6 },
+};

package/src/keyboard/components/HandleChipsInput.test.tsx

@@ -0,0 +1,35 @@
+/** Backspace on the empty field pulls the last chip back in to edit, rather than deleting it. */
+
+import React, { useState } from "react";
+import { describe, expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import { DARK } from "../../appearance/theme";
+import { press, settle } from "../../testing/test-support";
+import { HandleChipsInput } from "./HandleChipsInput";
+
+/** A controlled host so onChange edits flow back into the rendered list, like the wizard. */
+function Harness({ initial }: { initial: string[] }): React.ReactNode {
+  const [logins, setLogins] = useState(initial);
+
+  return <HandleChipsInput logins={logins} onChange={setLogins} theme={DARK} />;
+}
+
+describe("HandleChipsInput", () => {
+  test("backspace on the empty field restores the last chip as editable text", async () => {
+    // Arrange - one committed chip and an empty input showing its placeholder
+    const setup = await testRender(<Harness initial={["octocat"]} />, { width: 48, height: 6 });
+
+    await settle(setup);
+    expect(setup.captureCharFrame()).toContain("handle");
+
+    // Act - backspace with the input empty
+    await press(setup, "backspace");
+
+    // Assert - the handle is back in the field (placeholder gone), not deleted
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("octocat");
+    expect(frame).not.toContain("handle");
+    setup.renderer.destroy();
+  });
+});

package/src/keyboard/components/HandleChipsInput.tsx

@@ -0,0 +1,143 @@
+/**
+ * A tag-style input for GitHub logins: each added handle is an inline chip with
+ * a hover × to remove, and a trailing one-line field where enter adds the next
+ * and backspace on an empty field drops the last. Controlled - the caller owns
+ * the list and receives every change.
+ */
+
+import React, { useEffect, useRef, useState } from "react";
+import { useKeyboard } from "@opentui/react";
+import type { KeyBinding, TextareaRenderable } from "@opentui/core";
+import type { Theme } from "../../appearance/theme";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+import { NERD } from "../../ui/components/primitives/icons";
+
+// enter adds the handle rather than inserting a newline into the one-line field
+const ADD_KEY_BINDINGS: KeyBinding[] = [{ name: "return", action: "submit" }];
+
+function HandleChip({
+  login,
+  onRemove,
+  tokens,
+}: {
+  login: string;
+  onRemove: () => void;
+  tokens: Theme;
+}): React.ReactNode {
+  const [hovered, setHovered] = useState(false);
+
+  return (
+    <box
+      onMouseOver={() => setHovered(true)}
+      onMouseOut={() => setHovered(false)}
+      style={{
+        flexDirection: "row",
+        flexShrink: 0,
+        marginRight: 2,
+        paddingLeft: 1,
+        backgroundColor: tokens.border,
+      }}
+    >
+      <text fg={tokens.text} style={{ wrapMode: "none" }}>{`@${login}`}</text>
+      <box
+        onMouseUp={(event) => {
+          event.stopPropagation();
+          onRemove();
+        }}
+        style={{ paddingLeft: 1, paddingRight: 1 }}
+      >
+        <text fg={tokens.textDim}>{hovered ? NERD.close : " "}</text>
+      </box>
+    </box>
+  );
+}
+
+export interface HandleChipsInputProps {
+  logins: string[];
+  onChange: (logins: string[]) => void;
+  focused?: boolean;
+  onEmptyBackspace?: () => void;
+  theme?: Theme;
+}
+
+export function HandleChipsInput({
+  logins,
+  onChange,
+  focused = true,
+  onEmptyBackspace,
+  theme,
+}: HandleChipsInputProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const inputRef = useRef<TextareaRenderable | null>(null);
+  // the text the current field generation mounts with; a remount reseeds it
+  const [seed, setSeed] = useState("");
+  const [inputGeneration, setInputGeneration] = useState(0);
+
+  useEffect(() => {
+    const input = inputRef.current;
+
+    if (!input || !focused) return;
+    input.focus();
+    input.cursorOffset = seed.length; // land the caret at the end of the seeded text
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [inputGeneration, focused]);
+
+  const reseed = (text: string): void => {
+    setSeed(text);
+    setInputGeneration((generation) => generation + 1);
+  };
+
+  const addDraft = (): void => {
+    const handle = (inputRef.current?.plainText ?? "").trim().replace(/^@/, "").toLowerCase();
+
+    if (handle && !logins.includes(handle)) onChange([...logins, handle]);
+    reseed("");
+  };
+
+  useKeyboard((key) => {
+    if (!focused) return;
+    if (key.name !== "backspace" || (inputRef.current?.plainText ?? "").length > 0) return;
+    // backspace on an empty field pulls the last chip back in to edit; with none left, collapse
+    if (logins.length > 0) {
+      const last = logins[logins.length - 1]!;
+
+      onChange(logins.slice(0, -1));
+      reseed(last);
+    } else {
+      onEmptyBackspace?.();
+    }
+  });
+
+  return (
+    <box style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "center" }}>
+      {logins.map((login) => (
+        <HandleChip
+          key={login}
+          login={login}
+          onRemove={() => onChange(logins.filter((entry) => entry !== login))}
+          tokens={tokens}
+        />
+      ))}
+      <box style={{ flexDirection: "row", flexShrink: 0 }}>
+        <text fg={tokens.textDim}>{"@"}</text>
+        <textarea
+          key={inputGeneration}
+          ref={inputRef}
+          focused
+          initialValue={seed}
+          placeholder="handle"
+          keyBindings={ADD_KEY_BINDINGS}
+          onSubmit={addDraft}
+          style={{
+            height: 1,
+            width: 16,
+            backgroundColor: tokens.elevated,
+            focusedBackgroundColor: tokens.elevated,
+            textColor: tokens.text,
+            focusedTextColor: tokens.text,
+          }}
+        />
+      </box>
+    </box>
+  );
+}

package/src/keyboard/components/KeybindsDialog.stories.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { KeybindsDialog } from "./KeybindsDialog";
+
+export const meta: StoryMeta = { title: "Overlays/KeybindsDialog" };
+
+const SECTIONS = [
+  {
+    title: "Review",
+    entries: [
+      { keys: "j / k", label: "move" },
+      { keys: "v", label: "span" },
+      { keys: "c", label: "comment" },
+      { keys: "enter", label: "submit" },
+    ],
+  },
+  {
+    title: "Submit",
+    entries: [
+      { keys: "← / →", label: "message" },
+      { keys: "esc", label: "cancel" },
+    ],
+  },
+];
+
+export const Cheatsheet: Story = {
+  render: () => <KeybindsDialog sections={SECTIONS} />,
+  expectedColors: [DARK.accent],
+  size: { width: 70, height: 24 },
+};