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

package/src/path-view.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, test } from "bun:test";
+import {
+  appendEntry,
+  createBranch,
+  historyFromLinear,
+  navigateTo,
+  switchBranch,
+  type SessionHistory,
+} from "./history";
+import { applyPathView, sharePublicationView, viewFollowing, viewOfPath } from "./path-view";
+import type { Annotation, Thread } from "./types";
+
+const AT = "2026-09-01T10:00:00.000Z";
+
+function annotation(id: string): Annotation {
+  return {
+    id,
+    kind: "comment",
+    anchor: { quote: "q", prefix: "", suffix: "" },
+    body: id,
+    createdAt: AT,
+  };
+}
+
+/** rev1 (agent) -> comment a1 -> reviewer edit -> comment a2, all on main. */
+function threaded(): SessionHistory {
+  let history = historyFromLinear({
+    id: "ses_1",
+    revisions: [{ revision: 1, content: "Plan v1", submittedAt: AT }],
+    annotations: [],
+    message: null,
+    createdAt: AT,
+  });
+
+  history = appendEntry(history, { type: "comment", annotationId: "a1", createdAt: AT }).history;
+  history = appendEntry(history, {
+    type: "revision",
+    by: "reviewer",
+    content: "Plan v1 edited",
+    textCuts: [{ start: 5, end: 8, quote: "v1 " }],
+    createdAt: AT,
+  }).history;
+  history = appendEntry(history, { type: "comment", annotationId: "a2", createdAt: AT }).history;
+
+  return history;
+}
+
+describe("viewOfPath", () => {
+  test("the artifact is the agent's last revision and the reviewer's head is the working copy", () => {
+    // Act
+    const view = viewOfPath(threaded(), [annotation("a1"), annotation("a2")]);
+
+    // Assert
+    expect(view.content).toBe("Plan v1");
+    expect(view.workingCopy).toBe("Plan v1 edited");
+    expect(view.textCuts).toEqual([{ start: 5, end: 8, quote: "v1 " }]);
+    expect(view.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
+    expect(view.shelvedAnnotations).toEqual([]);
+  });
+
+  test("navigating back shelves the comments the path no longer reaches, and forward again unshelves them", () => {
+    // Arrange: a branch that stays at the full path, main moved back to the first comment
+    let history = createBranch(threaded(), "full");
+    const known = [annotation("a1"), annotation("a2")];
+
+    history = switchBranch(history, "main");
+    history = navigateTo(history, history.entries[1]!.id);
+
+    // Act
+    const back = viewOfPath(history, known);
+    const forward = viewOfPath(
+      switchBranch(history, "full"),
+      back.annotations.concat(back.shelvedAnnotations),
+    );
+
+    // Assert
+    expect(back.workingCopy).toBeUndefined();
+    expect(back.textCuts).toBeUndefined();
+    expect(back.annotations.map((entry) => entry.id)).toEqual(["a1"]);
+    expect(back.shelvedAnnotations.map((entry) => entry.id)).toEqual(["a2"]);
+    expect(forward.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
+    expect(forward.textCuts).toEqual([{ start: 5, end: 8, quote: "v1 " }]);
+    expect(forward.shelvedAnnotations).toEqual([]);
+  });
+
+  test("a removed comment stays shelved, not deleted", () => {
+    // Arrange
+    let history = threaded();
+
+    history = appendEntry(history, {
+      type: "comment-removed",
+      annotationId: "a1",
+      createdAt: AT,
+    }).history;
+
+    // Act
+    const view = viewOfPath(history, [annotation("a1"), annotation("a2")]);
+
+    // Assert
+    expect(view.annotations.map((entry) => entry.id)).toEqual(["a2"]);
+    expect(view.shelvedAnnotations.map((entry) => entry.id)).toEqual(["a1"]);
+  });
+});
+
+describe("applyPathView", () => {
+  test("writes the view into the record and removes the fields the view leaves empty", () => {
+    // Arrange
+    const session: Thread = {
+      schemaVersion: "1",
+      id: "ses_1",
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "plan", content: "old", meta: {} },
+      revisions: [],
+      annotations: [annotation("a2")],
+      shelvedAnnotations: [annotation("a1")],
+      workingCopy: "edited",
+      message: null,
+      status: "pending",
+      createdAt: AT,
+    };
+
+    // Act
+    applyPathView(session, {
+      content: "Plan v1",
+      workingCopy: undefined,
+      textCuts: undefined,
+      annotations: [annotation("a1"), annotation("a2")],
+      shelvedAnnotations: [],
+    });
+
+    // Assert
+    expect(session.artifact.content).toBe("Plan v1");
+    expect(session.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
+    expect("workingCopy" in session).toBe(false);
+    expect("shelvedAnnotations" in session).toBe(false);
+  });
+});
+
+describe("viewFollowing", () => {
+  test("a share carries one branch's path: its entries, tip, labels, and open comments, nothing shelved", () => {
+    // Arrange: main has a1 and an edit; a branch off a1 has its own comment; the owner stands on the branch
+    let history = threaded();
+
+    history = navigateTo(history, history.entries[1]!.id);
+    history = createBranch(history, "alt");
+    history = appendEntry(history, { type: "comment", annotationId: "b1", createdAt: AT }).history;
+    const session: Thread = {
+      schemaVersion: "1",
+      id: "ses_1",
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "plan", content: "Plan v1", meta: {} },
+      revisions: [],
+      annotations: [annotation("a1"), annotation("b1")],
+      shelvedAnnotations: [annotation("a2")],
+      workingCopy: "Plan v1 edited",
+      history,
+      message: null,
+      status: "pending",
+      createdAt: AT,
+    };
+
+    // Act
+    const shared = viewFollowing(session);
+
+    // Assert: main's path only, back at the first comment, no working copy, no shelf, the branch named
+    expect(shared.history!.branch).toBe("main");
+    expect(shared.history!.tips).toEqual({ main: history.entries[1]!.id });
+    expect(shared.history!.entries.map((entry) => entry.type)).toEqual(["revision", "comment"]);
+    expect(shared.annotations.map((entry) => entry.id)).toEqual(["a1"]);
+    expect("shelvedAnnotations" in shared).toBe(false);
+    expect("workingCopy" in shared).toBe(false);
+    // the owner's record is untouched
+    expect(session.annotations.map((entry) => entry.id)).toEqual(["a1", "b1"]);
+  });
+
+  test("a followed branch that no longer exists falls back to main", () => {
+    // Arrange: a plain main-only history, asked to follow a branch that is not there
+    const history = historyFromLinear({
+      id: "ses_1",
+      revisions: [{ revision: 1, content: "Plan v1", submittedAt: AT }],
+      annotations: [],
+      message: null,
+      createdAt: AT,
+    });
+    const session: Thread = {
+      schemaVersion: "1",
+      id: "ses_1",
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "plan", content: "Plan v1", meta: {} },
+      revisions: [],
+      annotations: [],
+      shares: [{ id: "p_test", requireAuth: false, allowlist: [], shareBranch: "gone" }],
+      history,
+      message: null,
+      status: "pending",
+      createdAt: AT,
+    };
+
+    // Act
+    const shared = viewFollowing(session);
+
+    // Assert: it does not throw, and falls back to main
+    expect(shared.history!.branch).toBe("main");
+    expect(shared.history!.branch).toBe("main");
+  });
+});
+
+test("a publication carries only its selected link's policy, without other owners or allowlists", () => {
+  const session: Thread = {
+    schemaVersion: "1",
+    id: "ses_1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "Plan", meta: {} },
+    revisions: [],
+    annotations: [],
+    message: null,
+    status: "pending",
+    createdAt: AT,
+    shares: [
+      { id: "p_other", owner: "SHA256:owner", requireAuth: true, allowlist: ["private-member"] },
+    ],
+  };
+  const shared = sharePublicationView(session, { requireAuth: true, allowlist: ["octocat"] });
+
+  expect(shared.shares).toEqual([
+    { id: session.id, requireAuth: true, allowlist: ["octocat"], shareBranch: "main" },
+  ]);
+  expect(session.shares![0]!.allowlist).toEqual(["private-member"]);
+  expect(
+    sharePublicationView(session, { requireAuth: false, allowlist: ["discarded"] }).shares![0]!
+      .allowlist,
+  ).toEqual([]);
+});

package/src/path-view.ts

@@ -0,0 +1,105 @@
+/**
+ * The linear view of a session's active path. Every client reads the artifact
+ * text, the working copy, and the comments straight off the record, so the
+ * record keeps them materialized; this module recomputes them from the path
+ * whenever a tip moves. Comments the path does not reach are shelved, never
+ * dropped, so a later move can show them again.
+ */
+
+import { derivePath, followBranch, MAIN_BRANCH, pathOf, type SessionHistory } from "./history";
+import type { Annotation, ShareLink, SharePolicy, Thread, TextCut } from "./types";
+
+export interface PathView {
+  content: string;
+  workingCopy: string | undefined;
+  textCuts: TextCut[] | undefined;
+  annotations: Annotation[];
+  shelvedAnnotations: Annotation[];
+}
+
+/**
+ * Fold the active path over every comment the session holds, on or off the
+ * path. Comments on the path whose objects are gone stay gone.
+ */
+export function viewOfPath(history: SessionHistory, known: Annotation[]): PathView {
+  const derived = derivePath(history);
+  const agentHead = pathOf(history)
+    .filter((entry) => entry.type === "revision" && entry.by === "agent")
+    .at(-1);
+  const content = agentHead?.type === "revision" ? agentHead.content : derived.head.content;
+  const byId = new Map(known.map((annotation) => [annotation.id, annotation]));
+  const annotations: Annotation[] = [];
+
+  for (const id of derived.annotationIds) {
+    const annotation = byId.get(id);
+
+    if (annotation) {
+      annotations.push(annotation);
+      byId.delete(id);
+    }
+  }
+
+  return {
+    content,
+    workingCopy: derived.head.content === content ? undefined : derived.head.content,
+    textCuts: derived.head.by === "reviewer" ? derived.head.textCuts : undefined,
+    annotations,
+    shelvedAnnotations: [...byId.values()],
+  };
+}
+
+/** Write a path view back into a record, in place; absent fields are removed. */
+export function applyPathView(session: Thread, view: PathView): void {
+  session.artifact = { ...session.artifact, content: view.content };
+  session.annotations = view.annotations;
+  if (view.textCuts?.length) session.textCuts = view.textCuts;
+  else delete session.textCuts;
+  if (view.workingCopy === undefined) delete session.workingCopy;
+  else session.workingCopy = view.workingCopy;
+  if (view.shelvedAnnotations.length === 0) delete session.shelvedAnnotations;
+  else session.shelvedAnnotations = view.shelvedAnnotations;
+}
+
+/**
+ * The record as a share carries it: the followed branch's path and what it
+ * shows, with no other branch, no shelved comment, and no working copy of the
+ * owner's. A followed branch that no longer exists falls back to main. A record
+ * without a history travels as it is.
+ */
+export function viewFollowing(session: Thread, branch?: string): Thread {
+  const asked = branch ?? session.shares?.at(-1)?.shareBranch ?? MAIN_BRANCH;
+  // a branch that no longer exists falls back to main, matching the daemon
+  const followed =
+    session.history && session.history.tips[asked] === undefined ? MAIN_BRANCH : asked;
+  const shared: Thread = { ...session };
+
+  if (!session.history) return shared;
+  const history = followBranch(session.history, followed);
+  const known = [...session.annotations, ...(session.shelvedAnnotations ?? [])];
+
+  shared.history = history;
+  applyPathView(shared, viewOfPath(history, known));
+  delete shared.shelvedAnnotations;
+
+  return shared;
+}
+
+/** Publish one link's branch and policy, without carrying other links; the gateway assigns its final ID and owner. */
+export function sharePublicationView(
+  session: Thread,
+  publication: SharePolicy & Pick<ShareLink, "shareBranch">,
+): Thread {
+  const shared = viewFollowing(session, publication.shareBranch ?? session.history?.branch);
+
+  return {
+    ...shared,
+    shares: [
+      {
+        id: session.id,
+        requireAuth: publication.requireAuth,
+        allowlist: publication.requireAuth ? publication.allowlist : [],
+        shareBranch: shared.history?.branch ?? publication.shareBranch ?? MAIN_BRANCH,
+      },
+    ],
+  };
+}

package/src/share-access.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { isShareViewerAllowed } from "./share-access";
+
+describe("isShareViewerAllowed", () => {
+  test("a public link admits an unauthenticated viewer", () => {
+    expect(isShareViewerAllowed({ requireAuth: false, allowlist: [] }, undefined)).toBe(true);
+  });
+  test("an unauthenticated viewer is refused", () => {
+    expect(isShareViewerAllowed({ requireAuth: true, allowlist: ["octocat"] }, undefined)).toBe(
+      false,
+    );
+  });
+
+  test("a member is admitted, case-insensitively", () => {
+    expect(isShareViewerAllowed({ requireAuth: true, allowlist: ["OctoCat"] }, "octocat")).toBe(
+      true,
+    );
+  });
+
+  test("a non-member is refused", () => {
+    expect(isShareViewerAllowed({ requireAuth: true, allowlist: ["octocat"] }, "hubot")).toBe(
+      false,
+    );
+  });
+
+  test("an empty allowlist admits no one", () => {
+    expect(isShareViewerAllowed({ requireAuth: true, allowlist: [] }, "octocat")).toBe(false);
+  });
+});

package/src/share-access.ts

@@ -0,0 +1,14 @@
+/** Whether a github login may view a private share; membership is case-insensitive and an unauthenticated viewer is never allowed. */
+
+import type { SharePolicy } from "./types";
+
+export function isShareViewerAllowed(
+  policy: SharePolicy,
+  githubLogin: string | undefined,
+): boolean {
+  if (!policy.requireAuth) return true;
+  if (githubLogin === undefined) return false;
+  const login = githubLogin.toLowerCase();
+
+  return policy.allowlist.some((allowed) => allowed.toLowerCase() === login);
+}

package/src/thread-agent.ts

@@ -0,0 +1,92 @@
+import type { Anchor, OperationReceipt } from "./types";
+
+/** An agent message keeps its identity after streaming and across reconnects. */
+export interface AgentMessage {
+  id: string;
+  role: "user" | "agent";
+  text: string;
+  complete: boolean;
+  revision: number;
+  submissionId?: string;
+}
+
+/** Tool activity belongs to a turn; its output is bounded by the daemon. */
+export interface AgentTool {
+  id: string;
+  turnId: string;
+  title: string;
+  kind: string;
+  status: "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+  output: string;
+  locations: { path: string; line?: number }[];
+}
+
+/** Agent feedback targets a completed message, never a changing stream. */
+export interface AgentComment {
+  id: string;
+  messageId: string;
+  anchor: Anchor;
+  body: string;
+  sent: boolean;
+  replyTo?: string;
+  author?: string;
+}
+
+/** Permission options come from the active agent request, not client defaults. */
+export interface AgentPermission {
+  id: string;
+  title: string;
+  options: { optionId: string; name: string; kind: string }[];
+}
+
+/** Agent lifecycle state distinguishes a waiting permission from an active turn. */
+export type AgentPhase =
+  | { kind: "idle" }
+  | { kind: "running" }
+  | { kind: "permission"; permission: AgentPermission }
+  | { kind: "failed"; error: string };
+
+/** A thread agent transcript is separate from the artifact and its revision history. */
+export interface ThreadAgentState {
+  threadId: string;
+  harness?: { id: string; label: string; sessionId?: string };
+  phase: AgentPhase;
+  messages: AgentMessage[];
+  tools: AgentTool[];
+  comments: AgentComment[];
+  submissions?: AgentSubmission[];
+  promptOperations?: (OperationReceipt<string[]> & {
+    outcome?: "completed" | "failed" | "cancelled";
+  })[];
+  configOptions?: AgentConfigOption[];
+}
+
+/** A submission freezes its input; retry keeps the same mirror and discussion origin. */
+export interface AgentSubmission {
+  id: string;
+  commentId?: string;
+  messageId?: string;
+  prompt: string;
+  quote?: string;
+  context?: string;
+  status: "queued" | "running" | "completed" | "failed";
+  cancelled?: boolean;
+}
+
+/** Model and reasoning choices are advertised by the harness, never invented by the UI. */
+export interface AgentConfigOption {
+  id: string;
+  name: string;
+  category?: string;
+  currentValue: string;
+  options: { value: string; name: string }[];
+}
+
+/** Prompt submission preserves operation identity while optional context remains separate from input. */
+export interface AgentPromptRequest {
+  id: string;
+  text: string;
+  context?: string;
+  retry?: string;
+  operationId?: string;
+}

package/src/thread-surface.test.ts

@@ -0,0 +1,6 @@
+import { expect, test } from "bun:test";
+import { manualThreadOpenCommand } from "./thread-surface";
+
+test("manual Thread command uses the shared harness wording", () => {
+  expect(manualThreadOpenCommand("ses_123")).toBe("Open cueloop threads: cueloop ses_123");
+});

package/src/thread-surface.ts

@@ -0,0 +1,6 @@
+export type ThreadSurfaceOpenStatus = "opened" | "focused" | "disabled" | "unavailable" | "failed";
+
+/** Give a harness the same manual command when any terminal integration cannot open. */
+export function manualThreadOpenCommand(threadId: string): string {
+  return `Open cueloop threads: cueloop ${threadId}`;
+}

package/src/types.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import {
+  annotationTarget,
+  ARTIFACT_TYPES,
+  WORKFLOW_KINDS,
+  WORKFLOW_SKILL_KINDS,
+  isArtifactType,
+  isMarkdownArtifact,
+  newAnnotationId,
+  messageAllows,
+} from "./types";
+
+describe("annotationTarget", () => {
+  test("an annotation with no target means the reviewed artifact", () => {
+    expect(annotationTarget({ target: undefined })).toEqual({ kind: "artifact" });
+  });
+
+  test("a stamped target is returned as-is", () => {
+    const target = { kind: "file", path: "src/x.ts", rev: "worktree" } as const;
+
+    expect(annotationTarget({ target })).toBe(target);
+  });
+});
+
+describe("ARTIFACT_TYPES", () => {
+  test("names every primitive exactly once", () => {
+    expect([...ARTIFACT_TYPES].sort()).toEqual(["diff", "plan", "prototype", "reply"]);
+    expect(new Set(ARTIFACT_TYPES).size).toBe(ARTIFACT_TYPES.length);
+  });
+
+  test("isArtifactType accepts every member and rejects strangers", () => {
+    for (const type of ARTIFACT_TYPES) expect(isArtifactType(type)).toBe(true);
+    expect(isArtifactType("blueprint")).toBe(false);
+    expect(isArtifactType("")).toBe(false);
+  });
+});
+
+describe("WORKFLOW_KINDS", () => {
+  test("review and refine are workflows, not artifact types", () => {
+    expect(WORKFLOW_KINDS).toEqual(["plan", "reply", "prototype", "diff", "review", "refine"]);
+    expect(isArtifactType("review")).toBe(false);
+    expect(isArtifactType("refine")).toBe(false);
+  });
+});
+
+describe("WORKFLOW_SKILL_KINDS", () => {
+  test("includes the live pairing skill without adding it to artifact submission workflows", () => {
+    expect(WORKFLOW_SKILL_KINDS).toEqual([...WORKFLOW_KINDS, "pair"]);
+    expect(WORKFLOW_KINDS).not.toContain("pair");
+  });
+});
+
+describe("messageAllows", () => {
+  test("only approve maps to allow", () => {
+    expect(messageAllows("approved")).toBe(true);
+    expect(messageAllows("comment")).toBe(false);
+    expect(messageAllows("changes_requested")).toBe(false);
+  });
+});
+
+describe("isMarkdownArtifact", () => {
+  test("plan, reply, and prototype are markdown; diff is not", () => {
+    expect(isMarkdownArtifact("plan")).toBe(true);
+    expect(isMarkdownArtifact("reply")).toBe(true);
+    expect(isMarkdownArtifact("prototype")).toBe(true);
+    expect(isMarkdownArtifact("diff")).toBe(false);
+  });
+});
+
+describe("newAnnotationId", () => {
+  test("unique by construction within a process, even on one millisecond", () => {
+    // Act
+    const ids = new Set(Array.from({ length: 10_000 }, () => newAnnotationId()));
+
+    // Assert
+    expect(ids.size).toBe(10_000);
+    for (const id of ids) expect(id).toMatch(/^a_[0-9a-z]+_[0-9a-z]+$/);
+  });
+});