cueloop 0.1.0-alpha.23 → 0.1.0-alpha.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -10,9 +10,9 @@
     ".": "./src/main.ts"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.23",
-    "@cueloop/daemon": "0.1.0-alpha.23",
-    "@cueloop/client": "0.1.0-alpha.23"
+    "@cueloop/schema": "0.1.0-alpha.25",
+    "@cueloop/daemon": "0.1.0-alpha.25",
+    "@cueloop/client": "0.1.0-alpha.25"
   },
   "publishConfig": {
     "access": "public"

package/src/main.ts

@@ -74,13 +74,11 @@ async function main(): Promise<number> {
     }
     case "share": {
       const { positional, flags } = parseArgs(argv.slice(1));
-      const { shareCommand } = await import("./share-command");
+      const { shareCommand, sharePullCommand } = await import("./share-command");
       const port = stringFlag(flags, "port");
-      return shareCommand({
-        sessionId: positional[0],
-        host: stringFlag(flags, "host"),
-        port: port !== undefined ? Number(port) : undefined,
-      });
+      const target = { host: stringFlag(flags, "host"), port: port !== undefined ? Number(port) : undefined };
+      if (positional[0] === "pull") return sharePullCommand({ ...target, sessionId: positional[1] });
+      return shareCommand({ ...target, sessionId: positional[0] });
     }
     case "review":
       return reviewEntry(argv.slice(1));
@@ -210,22 +208,31 @@ function printHelp(): void {
     [
       "cueloop - review surface for coding agents",
       "",
-      "usage:",
+      "usage: cueloop [command] [options]",
+      "",
+      "common commands:",
       "  cueloop                          open the inbox",
-      "  cueloop <session-id>             open one session",
       "  cueloop plan [id|title]          open the latest pending plan review (or one by id/title)",
-      "  cueloop diff [id|title]          open the latest pending diff review (or one by id/title);",
-      "                                   with a dirty working tree and no argument, create one instead",
-      "  cueloop review [id|title]        open the latest pending PR review (or one by id/title)",
+      "  cueloop diff [id|title]          review your working tree (untracked files included);",
+      "                                   with a clean tree, open the latest pending diff review",
       "  cueloop review <pr>              review a pull request (--no-tui prints the session)",
-      "  cueloop <plan|diff|review> --latest  open the latest pending review of that type",
-      "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
+      "",
+      "share:",
       "  cueloop serve [session-id]       share over ssh: observers are read-only,",
       "                                   you stay the controller (--port 2222, --host 127.0.0.1;",
       "                                   password-less - share the address deliberately)",
       "  cueloop share [session-id]       hand a plan to a teammate: copies one",
       "                                   ssh line (--host cueloop.dev, --port 22)",
+      "  cueloop share pull [session-id]  pull a teammate's annotations back into the plan",
+      "",
+      "open a specific review:",
+      "  cueloop <session-id>             open one session",
+      "  cueloop review [id|title]        open the latest pending PR review (or one by id/title)",
+      "  cueloop <plan|diff|review> --latest  open the latest pending review of that type",
+      "",
+      "scripting:",
       "  cueloop session <verb> [flags]   script the daemon (create|get|list|wait|annotate|resolve|submit-revision)",
+      "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
       "  cueloop daemon                   run the daemon in the foreground",
     ].join("\n"),
   );

package/src/share-command.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, mock, test } from "bun:test";
-import { SCHEMA_VERSION, type ReviewSession } from "@cueloop/schema";
+import { SCHEMA_VERSION, type Annotation, type ReviewSession } from "@cueloop/schema";
 import type { SessionClient } from "@cueloop/daemon/client";
-import { shareSession, type ShareDeps } from "./share-command";
+import { pullSession, shareSession, type PullDeps, type ShareDeps } from "./share-command";
 
-function sessionFixture(id: string): ReviewSession {
+function sessionFixture(id: string, overrides: Partial<ReviewSession> = {}): ReviewSession {
   return {
     schemaVersion: SCHEMA_VERSION,
     id,
@@ -14,14 +14,31 @@ function sessionFixture(id: string): ReviewSession {
     verdict: null,
     status: "pending",
     createdAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
   };
 }
 
-/** A SessionClient that answers get/list from a fixed list. */
+function annotationFixture(id: string, author?: string): Annotation {
+  const base: Annotation = { id, kind: "comment", anchor: { quote: "Plan", prefix: "", suffix: "" }, body: "note", createdAt: "2026-01-01T00:00:00.000Z" };
+  return author ? { ...base, author } : base;
+}
+
+/** A SessionClient that answers get/list from a fixed list and records the share/merge verbs. */
 function fakeClient(sessions: ReviewSession[]): SessionClient {
   return {
     sessionGet: async (id: string) => sessions.find((session) => session.id === id)!,
     sessionList: async () => sessions,
+    sessionSetShareId: mock(async (id: string, shareId: string) => {
+      const session = sessions.find((candidate) => candidate.id === id)!;
+      session.shareId = shareId;
+      return session;
+    }),
+    sessionMergeAnnotations: mock(async (id: string, incoming: Annotation[]) => {
+      const session = sessions.find((candidate) => candidate.id === id)!;
+      const known = new Set(session.annotations.map((annotation) => annotation.id));
+      for (const annotation of incoming) if (!known.has(annotation.id)) session.annotations.push(annotation);
+      return session;
+    }),
   } as unknown as SessionClient;
 }
 
@@ -84,4 +101,79 @@ describe(shareSession, () => {
     expect(deps.lines[0]).toContain("no plan to share");
     expect(deps.publish).not.toHaveBeenCalled();
   });
+
+  test("stamps the share id on the session so a later pull can find it", async () => {
+    // Arrange
+    const session = sessionFixture("ses_1");
+    const client = fakeClient([session]);
+    const deps = depsSpy();
+
+    // Act
+    await shareSession(client, { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(client.sessionSetShareId).toHaveBeenCalledWith("ses_1", "p_abc123xy");
+  });
+});
+
+function pullDepsSpy(remote: ReviewSession): PullDeps & { lines: string[] } {
+  const lines: string[] = [];
+  return { pull: mock(async () => remote), out: (message: string) => void lines.push(message), lines };
+}
+
+describe(pullSession, () => {
+  test("unions collaborator notes in, ignoring the planner's own unauthored notes", async () => {
+    // Arrange - the planner's own note carries no author; the collaborator's does
+    const local = sessionFixture("ses_1", { shareId: "p_abc123xy", annotations: [annotationFixture("mine")] });
+    const client = fakeClient([local]);
+    const remote = sessionFixture("ses_1", { annotations: [annotationFixture("mine"), annotationFixture("theirs", "SHA256:mate")] });
+    const deps = pullDepsSpy(remote);
+
+    // Act
+    const code = await pullSession(client, { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(code).toBe(0);
+    expect(deps.pull).toHaveBeenCalledWith("p_abc123xy", { host: undefined, port: undefined });
+    expect(local.annotations.map((annotation) => annotation.id)).toEqual(["mine", "theirs"]);
+    expect(deps.lines).toEqual(["pulled 1 new annotation"]);
+  });
+
+  test("does not resurrect a note the planner deleted locally after sharing", async () => {
+    // Arrange - the planner deleted "mine" locally; the share blob still carries it, unauthored
+    const local = sessionFixture("ses_1", { shareId: "p_abc123xy", annotations: [] });
+    const deps = pullDepsSpy(sessionFixture("ses_1", { annotations: [annotationFixture("mine")] }));
+
+    // Act
+    await pullSession(fakeClient([local]), { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(local.annotations).toEqual([]);
+    expect(deps.lines).toEqual(["no new annotations"]);
+  });
+
+  test("reports when nothing new came back", async () => {
+    // Arrange
+    const local = sessionFixture("ses_1", { shareId: "p_abc123xy", annotations: [annotationFixture("theirs", "SHA256:mate")] });
+    const deps = pullDepsSpy(sessionFixture("ses_1", { annotations: [annotationFixture("theirs", "SHA256:mate")] }));
+
+    // Act
+    await pullSession(fakeClient([local]), { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(deps.lines).toEqual(["no new annotations"]);
+  });
+
+  test("refuses to pull a plan that was never shared", async () => {
+    // Arrange
+    const deps = pullDepsSpy(sessionFixture("ses_1"));
+
+    // Act
+    const code = await pullSession(fakeClient([sessionFixture("ses_1")]), { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(code).toBe(1);
+    expect(deps.lines[0]).toContain("no shared plan");
+    expect(deps.pull).not.toHaveBeenCalled();
+  });
 });

package/src/share-command.ts

@@ -7,7 +7,7 @@
  */
 
 import { DaemonClient, type SessionClient } from "@cueloop/daemon/client";
-import { publishShare, type ShareResult, type ShareTarget } from "@cueloop/client";
+import { collaboratorAnnotations, publishShare, pullShare, shareIdFromLine, type ShareResult, type ShareTarget } from "@cueloop/client";
 import type { ReviewSession } from "@cueloop/schema";
 
 export interface ShareParams {
@@ -22,7 +22,13 @@ export interface ShareDeps {
   out: (message: string) => void;
 }
 
+export interface PullDeps {
+  pull: (shareId: string, target: ShareTarget) => Promise<ReviewSession>;
+  out: (message: string) => void;
+}
+
 const defaultDeps: ShareDeps = { publish: publishShare, out: (message) => console.log(message) };
+const defaultPullDeps: PullDeps = { pull: pullShare, out: (message) => console.log(message) };
 
 /** Connect to the local daemon, then share the chosen session. */
 export async function shareCommand(params: ShareParams, deps: ShareDeps = defaultDeps): Promise<number> {
@@ -34,7 +40,17 @@ export async function shareCommand(params: ShareParams, deps: ShareDeps = defaul
   }
 }
 
-/** The orchestration, over any SessionClient - the seam the tests drive. */
+/** Connect to the local daemon, then pull collaborator notes for the plan. */
+export async function sharePullCommand(params: ShareParams, deps: PullDeps = defaultPullDeps): Promise<number> {
+  const client = await DaemonClient.connect({ home: params.home, autostart: true });
+  try {
+    return await pullSession(client, params, deps);
+  } finally {
+    client.close();
+  }
+}
+
+/** The share orchestration, over any SessionClient - the seam the tests drive. */
 export async function shareSession(client: SessionClient, params: ShareParams, deps: ShareDeps): Promise<number> {
   const session = await pickSession(client, params.sessionId);
   if (!session) {
@@ -42,13 +58,44 @@ export async function shareSession(client: SessionClient, params: ShareParams, d
     return 1;
   }
   const { line, copied } = await deps.publish(session, { host: params.host, port: params.port });
+  const shareId = shareIdFromLine(line);
+  if (shareId) await client.sessionSetShareId(session.id, shareId);
   deps.out(copied ? `share link copied - ${line}` : line);
   return 0;
 }
 
+/**
+ * Pull the share's current session and union its annotations into the local
+ * plan. Union-by-id keeps the planner's own notes; only collaborators' new
+ * ones land. The gateway lets only the fingerprint that shared it pull.
+ */
+export async function pullSession(client: SessionClient, params: ShareParams, deps: PullDeps): Promise<number> {
+  const session = await pickSharedSession(client, params.sessionId);
+  if (!session) {
+    deps.out("no shared plan to pull - run `cueloop share` first");
+    return 1;
+  }
+  const remote = await deps.pull(session.shareId!, { host: params.host, port: params.port });
+  const before = session.annotations.length;
+  const merged = await client.sessionMergeAnnotations(session.id, collaboratorAnnotations(remote));
+  const added = merged.annotations.length - before;
+  deps.out(added > 0 ? `pulled ${added} new annotation${added === 1 ? "" : "s"}` : "no new annotations");
+  return 0;
+}
+
 /** The named session, or the most recent one when no id is given. */
 async function pickSession(client: SessionClient, sessionId?: string): Promise<ReviewSession | null> {
   if (sessionId) return client.sessionGet(sessionId);
   const sessions = await client.sessionList();
   return sessions.at(-1) ?? null;
 }
+
+/** The named session (if shared), or the most recent shared one. */
+async function pickSharedSession(client: SessionClient, sessionId?: string): Promise<ReviewSession | null> {
+  if (sessionId) {
+    const session = await client.sessionGet(sessionId);
+    return session.shareId ? session : null;
+  }
+  const sessions = await client.sessionList();
+  return sessions.filter((session) => session.shareId).at(-1) ?? null;
+}