@cueloop/schema 0.1.0-alpha.10 → 0.1.0-alpha.101

package/src/types.ts

@@ -1,38 +1,121 @@
 /**
- * The ReviewSession primitive (map #2, #9). Everything in cueloop renders,
- * annotates, or resolves this one noun. This module is pure data shapes -
- * no IO, no dependencies.
+ * The Thread primitive. Everything in cueloop renders, annotates, or
+ * extends this one noun. This module is pure data shapes - no IO, no
+ * dependencies beyond the history shapes.
  */
 
+import type { SessionHistory } from "./history";
+
 export const SCHEMA_VERSION = "1";
 
-/** A workspace is a repo/branch context holding review sessions. */
+/** A workspace is a repo/branch context holding threads. */
 export interface WorkspaceKey {
   repoRoot: string;
   branch: string;
+  rootCommit?: string;
+  remote?: string;
 }
 
-export type ArtifactType = "plan" | "diff";
+/**
+ * What kind of artifact a thread holds. `plan` and `reply` are both
+ * markdown documents (see isMarkdownArtifact) - a plan is a proposal written
+ * forward, a reply is the agent's previous message pulled back for review.
+ * `diff` is a unified-diff patch; `prototype` is a component design doc (API /
+ * Composition / Callstack) in markdown, with an opt-in experimental pixel mode.
+ *
+ * One runtime union: every consumer that names the supported set - daemon
+ * wire validation, CLI flag parsing, adapter tool schemas - derives from this
+ * constant, so a new primitive extends them all without another hardcoded list.
+ */
+export const ARTIFACT_TYPES = ["plan", "diff", "prototype", "reply"] as const;
+
+export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
+
+/** Harness workflows; review and refine are compositions, never artifact types. */
+export const WORKFLOW_KINDS = ["plan", "reply", "prototype", "diff", "review", "refine"] as const;
+
+export type WorkflowKind = (typeof WORKFLOW_KINDS)[number];
+
+/** Agent skills installed by each harness, including workflows that don't submit an artifact. */
+export const WORKFLOW_SKILL_KINDS = [...WORKFLOW_KINDS, "pair"] as const;
+
+export type WorkflowSkillKind = (typeof WORKFLOW_SKILL_KINDS)[number];
+
+/** Trust-boundary guard: is this string one of the artifact primitives? */
+export function isArtifactType(value: string): value is ArtifactType {
+  return ARTIFACT_TYPES.some((candidate) => candidate === value);
+}
+
+/**
+ * Markdown artifacts (plan, reply, prototype) are block-parsed and quote-anchored,
+ * so they share the plan render path, first-heading title derivation, and revision
+ * drift-assist. A prototype is a component design doc (API / Composition / Callstack)
+ * by default; its opt-in experimental pixel mode is a client render override, not a
+ * different artifact. A diff (a patch) does not - keep this the one place that names
+ * the set, so a new markdown primitive joins here once.
+ */
+export function isMarkdownArtifact(type: ArtifactType): boolean {
+  return type === "plan" || type === "reply" || type === "prototype";
+}
 
 export interface ArtifactMeta {
+  workflow?: WorkflowKind;
   cwd?: string;
+  vcs?: string;
+  vcsChangeId?: string;
+  vcsRevisionId?: string;
   agent?: string;
-  /** Agent-native session id, for resume/fork context. */
   agentSessionId?: string;
-  /** Path to the plan file on disk, so feedback can reference it. */
   planPath?: string;
-  /** Pull request reference the diff came from, so the verdict can be posted back. */
+  prototypePath?: string;
   pr?: string;
-  /** herdr pane the submitting agent runs in - the review returns focus there. */
+  prBrief?: string;
+  prBaseSha?: string;
+  prHeadSha?: string;
+  prRefreshBaseSha?: string;
+  prRefreshHeadSha?: string;
+  prUrl?: string;
   herdrPane?: string;
   title?: string;
+  workbench?: boolean;
+  snapshot?: boolean;
+}
+
+/** VCS provenance for a submitted diff revision. */
+export interface DiffSource {
+  vcs: string;
+  changeId?: string;
+  revisionId?: string;
+  baseRevisionId?: string;
+}
+
+/** Full old/new contents of one changed file, keyed by its repo-relative path. */
+/** How a file changed, so curation emits the right create/delete headers. */
+export type DiffFileStatus = "added" | "modified" | "deleted";
+
+/**
+ * One reject decision of a diff review: a whole hunk, or one change block of
+ * it when `changeIndex` is set. The daemon curates the working copy from the
+ * full set, so every client sees the same patch.
+ */
+export interface HunkRejection {
+  path: string;
+  hunkIndex: number;
+  changeIndex?: number;
+}
+
+export interface DiffFileContents {
+  path: string;
+  oldContents: string;
+  newContents: string;
+  status: DiffFileStatus;
 }
 
 export interface Artifact {
   type: ArtifactType;
-  /** Markdown source for plans; unified-diff text for diffs. */
   content: string;
   meta: ArtifactMeta;
+  files?: DiffFileContents[];
 }
 
 /**
@@ -44,67 +127,211 @@ export interface Anchor {
   quote: string;
   prefix: string;
   suffix: string;
-  /** Index of the block the anchor was made in (hint). */
   blockIndex?: number;
-  /** Character offsets within that block's text (hint). */
+  endBlockIndex?: number;
   start?: number;
   end?: number;
+  selector?: string;
+}
+
+/** The annotation kind set is open; these are the built-ins. */
+export type AnnotationKind = "comment" | (string & {});
+
+/**
+ * The surface an annotation was made on. Name-only: the ref names the surface and the
+ * client loads that surface's text to resolve the quote anchor. Absent means the session's
+ * reviewed artifact, so every existing annotation keeps its meaning with no data change.
+ * A `file` target's `rev` doubles as the diff side: worktree for an added or context row,
+ * head for a deletion.
+ */
+export type AnnotationTarget =
+  | { kind: "artifact" }
+  | { kind: "file"; path: string; rev: "worktree" | "head" }
+  | { kind: "welcome" };
+
+/** The target an annotation resolves against; absent records mean the reviewed artifact. */
+export function annotationTarget(annotation: Pick<Annotation, "target">): AnnotationTarget {
+  return annotation.target ?? { kind: "artifact" };
 }
 
-/** The annotation kind set is open (map #2); these are the built-ins. */
-export type AnnotationKind = "comment" | "suggestion" | (string & {});
+/**
+ * Agent-authored context, not reviewer feedback: the guided walk's per-file
+ * notes (kind "note", anchored by the file path). Excluded from the feedback
+ * document and the reviewer's pending counts - an agent must never receive
+ * its own notes back as items to address.
+ */
+export function isAgentNote(annotation: Pick<Annotation, "kind">): boolean {
+  return annotation.kind === "note";
+}
 
 export interface Annotation {
   id: string;
   kind: AnnotationKind;
   anchor: Anchor;
-  /** Comment body, or the replacement text for suggestions. */
+  target?: AnnotationTarget;
   body: string;
-  /** Set by resolution when the quote can no longer be found. */
   orphan?: boolean;
+  author?: string;
+  reviewComment?: ReviewComment;
+  replyTo?: string;
+  resolution?: AnnotationResolution;
+  createdAt: string;
+}
+
+export const REVIEW_SEVERITIES = ["p0", "p1", "p2"] as const;
+
+export type ReviewSeverity = (typeof REVIEW_SEVERITIES)[number];
+
+/** Data needed to render and publish one agent-authored pull request comment. */
+export interface ReviewComment {
+  severity: ReviewSeverity;
+  title: string;
+  path: string;
+  line: number;
+  startLine?: number;
+  startAnchor?: Anchor;
+  side: "LEFT" | "RIGHT";
+  suggestion?: string;
+  prompt?: string;
+}
+
+export interface AnnotationResolution {
+  revision: number;
+  source: "agent" | "drift";
+}
+
+/** An annotation a revision has addressed; it leaves the default views. */
+export function isAddressed(annotation: Annotation): boolean {
+  return annotation.resolution !== undefined;
+}
+
+/** A harness session bound to a Thread. Harness identity stays outside the Thread itself. */
+export interface HarnessBinding {
+  id: string;
+  threadId: string;
+  harness: string;
+  harnessSessionId: string;
   createdAt: string;
+  approvedRetryMessageId?: string;
 }
 
-export type VerdictKind = "comment" | "approve" | "request_changes";
+/** Durable routing state for one Message sent to one harness binding. */
+export interface Delivery {
+  id: string;
+  messageId: string;
+  bindingId: string;
+  status: "pending" | "acknowledged";
+  createdAt: string;
+  acknowledgedAt?: string;
+}
+
+/** What a harness adapter pulls: routing state plus its immutable Message payload. */
+export interface PendingDelivery {
+  delivery: Delivery;
+  message: Message;
+}
+
+export const MESSAGE_OUTCOMES = ["comment", "approved", "changes_requested"] as const;
+
+export type MessageOutcome = (typeof MESSAGE_OUTCOMES)[number];
 
-export interface Verdict {
-  kind: VerdictKind;
+/** Durable acceptance records are committed together with the mutation they identify. */
+export interface OperationReceipt<Result> {
+  operationId: string;
+  fingerprint: string;
+  result: Result;
+}
+
+export interface Message {
+  id: string;
+  outcome: MessageOutcome;
   summary: string;
-  /** The one structured feedback document sent to the agent. */
-  feedback: string;
-  resolvedAt: string;
+  body: string;
+  annotations?: Annotation[];
+  sentAt: string;
 }
 
 export interface Revision {
   revision: number;
   content: string;
   submittedAt: string;
+  source?: DiffSource;
+  files?: DiffFileContents[];
 }
 
 export type SessionStatus = "pending" | "resolved";
 
-export interface ReviewSession {
+/**
+ * A person who authored annotations on a session. `id` is the stable key an
+ * annotation's `author` points at - the SSH fingerprint today, an OAuth id
+ * ("github:…") later. Provider-agnostic so those identities slot in unchanged.
+ */
+export interface Identity {
+  id: string;
+  provider: "ssh" | "github";
+  name?: string;
+  handle?: string;
+}
+
+/** A share link's public or private policy; a private link with an empty allowlist admits no viewers. */
+export type SharePolicy = Pick<ShareLink, "requireAuth" | "allowlist" | "agentEnabled">;
+
+/**
+ * One published share link for a thread. A thread can have several, each an
+ * independent gateway blob keyed by its own `id`. `name` is a local-only label
+ * to tell links apart; `requireAuth` gates the link behind the `allowlist` of
+ * GitHub logins (empty + requireAuth is a private link with no one added yet).
+ */
+export interface ShareLink {
+  id: string;
+  name?: string;
+  requireAuth: boolean;
+  allowlist: string[];
+  agentEnabled?: boolean;
+  owner?: string;
+  shareBranch?: string;
+}
+
+/** One exact character range removed from the submitted artifact source. */
+export interface TextCut {
+  start: number;
+  end: number;
+  quote: string;
+}
+
+/** A Thread carries share policy and ownership on each entry in shares. */
+export interface Thread {
   schemaVersion: string;
   id: string;
   workspace: WorkspaceKey;
   artifact: Artifact;
-  /** Revision history; artifact.content always equals the latest revision. */
   revisions: Revision[];
   annotations: Annotation[];
-  /**
-   * The reviewer's working copy of the artifact source (plan edits).
-   * Serializes as ONE unified diff against the submitted revision.
-   * Undefined = no direct edits.
-   */
+  history?: SessionHistory;
+  curation?: HunkRejection[];
   workingCopy?: string;
-  verdict: Verdict | null;
+  textCuts?: TextCut[];
+  viewedPaths?: string[];
+  messageOperations?: OperationReceipt<Message>[];
+  message: Message | null;
   status: SessionStatus;
   createdAt: string;
+  shelvedAnnotations?: Annotation[];
+  parentSessionId?: string;
+  shares?: ShareLink[];
+  participants?: Identity[];
 }
 
-/** comment and request_changes both map to deny in agent-native contracts. */
-export function verdictAllows(kind: VerdictKind): boolean {
-  return kind === "approve";
+/** Whether a Message releases a harness gate. */
+export function messageAllows(outcome: MessageOutcome): boolean {
+  return outcome === "approved";
+}
+
+let messageSeq = 0;
+
+/** A process-unique, time-sortable Message id for delivery deduplication. */
+export function newMessageId(): string {
+  return `msg_${Date.now().toString(36)}${(messageSeq++).toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
 
 /**
@@ -113,6 +340,7 @@ export function verdictAllows(kind: VerdictKind): boolean {
  * annotators in different processes on the same millisecond.
  */
 let annotationSeq = 0;
+
 export function newAnnotationId(): string {
   return `a_${Date.now().toString(36)}${(annotationSeq++).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
 }

package/src/working-copy.test.ts

@@ -1,5 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { cutBlock, restoreBlock, restoreLine, sourceChunk } from "./working-copy";
+import {
+  applyTextCuts,
+  blockCutSourceRange,
+  cutBlock,
+  cutTextRange,
+  mergeTextCut,
+  restoreTextCut,
+  restoreBlock,
+  restoreLine,
+  sourceChunk,
+} from "./working-copy";
 import { parseBlocks, type Block } from "./markdown";
 
 const BASE = `# Plan
@@ -18,92 +28,267 @@ const y = 2;
 \`\`\`
 `;
 
-function block(md: string, text: string): Block {
-  return parseBlocks(md).find((b) => b.text.includes(text))!;
+function block(markdown: string, text: string): Block {
+  return parseBlocks(markdown).find((block) => block.text.includes(text))!;
 }
 
 describe("sourceChunk", () => {
   test("returns the exact source lines a block occupies", () => {
     expect(sourceChunk(BASE, block(BASE, "first item"))).toBe("- first item");
-    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe("A paragraph that\nspans two lines.");
+    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe(
+      "A paragraph that\nspans two lines.",
+    );
   });
 
   test("code block chunk includes both fence lines", () => {
-    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe("```ts\nconst x = 1;\nconst y = 2;\n```");
+    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe(
+      "```ts\nconst x = 1;\nconst y = 2;\n```",
+    );
   });
 });
 
 describe("cutBlock", () => {
   test("removes the block lines and the blank line before it", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "spans two lines"));
+
+    // Assert
     expect(cut).not.toContain("spans two lines");
     expect(cut).toContain("## Context\n\n- first item");
   });
 
   test("cut at the start of the document leaves the leading blank line", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "Plan"));
+
+    // Assert
     expect(cut).not.toContain("# Plan");
     expect(cut.trimStart().startsWith("## Context")).toBe(true);
   });
 
   test("cut at the end of the document keeps the rest intact", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "const x"));
+
+    // Assert
     expect(cut).not.toContain("const x");
     expect(cut).toContain("- second item");
   });
+
+  test.each(["Plan", "spans two lines", "first item", "const x"])(
+    "reports the exact source interval cut from %s",
+    (text) => {
+      const target = block(BASE, text);
+      const range = blockCutSourceRange(BASE, target);
+
+      expect(BASE.slice(0, range.start) + BASE.slice(range.end)).toBe(cutBlock(BASE, target));
+    },
+  );
+});
+
+describe("cutTextRange", () => {
+  test("cuts only the selected characters inside a block", () => {
+    const paragraph = block(BASE, "spans two lines");
+    const start = paragraph.text.indexOf("paragraph");
+    const cut = cutTextRange(BASE, paragraph, start, paragraph, start + "paragraph".length);
+
+    expect(cut).toContain("A  that\nspans two lines.");
+    expect(cut).toContain("## Context");
+    expect(cut).toContain("- first item");
+  });
+
+  test("preserves a list marker around a partial cut", () => {
+    const item = block(BASE, "first item");
+    const cut = cutTextRange(BASE, item, 0, item, "first ".length);
+
+    expect(cut).toContain("- item");
+    expect(cut).not.toContain("- first item");
+  });
+
+  test.each([
+    ["heading", "# remove keep", "#  keep"],
+    ["ordered list", "12. remove keep", "12.  keep"],
+    ["fenced code", "```ts\nremove keep\n```", "```ts\n keep\n```"],
+    ["frontmatter", "---\nname: remove keep\n---", "---\nname:  keep\n---"],
+    ["table", "| remove | keep |\n| --- | --- |", "|  | keep |\n| --- | --- |"],
+  ])("preserves %s source markers", (_label, source, expected) => {
+    const target = block(source, "remove");
+    const start = target.text.indexOf("remove");
+
+    expect(cutTextRange(source, target, start, target, start + "remove".length)).toBe(expected);
+  });
+
+  test("cuts an exact range across marked quote lines", () => {
+    const source = "> keep alpha\n> remove beta\n> keep gamma";
+    const quote = parseBlocks(source)[0]!;
+    const start = quote.text.indexOf("alpha");
+    const end = quote.text.indexOf("keep gamma");
+
+    const cut = cutTextRange(source, quote, start, quote, end);
+
+    expect(cut).toBe("> keep keep gamma");
+  });
+
+  test("cuts an exact range across separate blocks", () => {
+    const source = "Keep before remove this.\n\n- remove that keep after";
+    const blocks = parseBlocks(source);
+    const first = blocks[0]!;
+    const second = blocks[1]!;
+    const start = first.text.indexOf("remove");
+    const end = second.text.indexOf("keep after");
+
+    const cut = cutTextRange(source, first, start, second, end);
+
+    expect(cut).toBe("Keep before keep after");
+  });
+});
+
+describe("exact text Cuts", () => {
+  test("stores and applies the selected source characters exactly", () => {
+    const source = "It lands under unin Threads then in the sidebar.";
+    const start = source.indexOf("under");
+    const end = source.indexOf(" in the sidebar");
+    const cuts = mergeTextCut(source, [], start, end);
+
+    expect(cuts).toEqual([{ start, end, quote: "under unin Threads then" }]);
+    expect(applyTextCuts(source, cuts)).toBe("It lands  in the sidebar.");
+  });
+
+  test("merges overlapping and adjacent ranges in one linear source interval", () => {
+    const source = "alpha beta gamma delta";
+    const first = mergeTextCut(source, [], 6, 10);
+    const merged = mergeTextCut(source, first, 10, 16);
+
+    expect(merged).toEqual([{ start: 6, end: 16, quote: "beta gamma" }]);
+    expect(applyTextCuts(source, merged)).toBe("alpha  delta");
+  });
+
+  test("returns the original references for no-op ranges", () => {
+    const source = "unchanged";
+    const cuts = [{ start: 0, end: 2, quote: "un" }];
+
+    expect(mergeTextCut(source, cuts, 4, 4)).toBe(cuts);
+    expect(applyTextCuts(source, [])).toBe(source);
+  });
+
+  test("applies out-of-order Cuts and ignores stale or overlapping records", () => {
+    const source = "alpha beta gamma";
+
+    expect(
+      applyTextCuts(source, [
+        { start: 11, end: 16, quote: "gamma" },
+        { start: 0, end: 5, quote: "alpha" },
+        { start: 2, end: 8, quote: "stale" },
+        { start: 6, end: 10, quote: "beta" },
+      ]),
+    ).toBe("  ");
+  });
+
+  test("restores an exact subrange without disturbing the rest of its Cut", () => {
+    const source = "alpha beta gamma delta";
+    const cuts = mergeTextCut(source, [], 6, 16);
+    const restored = restoreTextCut(source, cuts, 11, 16);
+
+    expect(restored).toEqual([{ start: 6, end: 11, quote: "beta " }]);
+    expect(applyTextCuts(source, restored ?? [])).toBe("alpha gamma delta");
+  });
+
+  test("does not restore across separate Cuts", () => {
+    const source = "alpha beta gamma delta";
+    const cuts = [
+      { start: 6, end: 10, quote: "beta" },
+      { start: 11, end: 16, quote: "gamma" },
+    ];
+
+    expect(restoreTextCut(source, cuts, 6, 16)).toBeNull();
+  });
 });
 
 describe("restoreBlock", () => {
   test("restoring the only cut returns undefined - back to pristine", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
+    // Arrange
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
     // the cut block re-enters before the code fence, the next surviving block
-    const next = parseBlocks(cut).find((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, cut, li, restoreLine(next, cut.split("\n").length));
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
+
+    // Act
+    const restored = restoreBlock(BASE, cut, listItem, restoreLine(next, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("restore after another edit returns the merged working copy", () => {
-    const li = block(BASE, "second item");
-    const edited = cutBlock(BASE, li).replace("first item", "first item reworded");
-    const next = parseBlocks(edited).find((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, edited, li, restoreLine(next, edited.split("\n").length));
+    // Arrange
+    const listItem = block(BASE, "second item");
+    const edited = cutBlock(BASE, listItem).replace("first item", "first item reworded");
+    const next = parseBlocks(edited).find((candidate) => candidate.kind === "code");
+
+    // Act
+    const restored = restoreBlock(
+      BASE,
+      edited,
+      listItem,
+      restoreLine(next, edited.split("\n").length),
+    );
+
+    // Assert
     expect(restored).toContain("- second item");
     expect(restored).toContain("first item reworded");
   });
 
   test("restore at the end of the document (no next block)", () => {
+    // Arrange
     const code = block(BASE, "const x");
     const cut = cutBlock(BASE, code);
+
+    // Act
     const restored = restoreBlock(BASE, cut, code, restoreLine(undefined, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("restore a multi-line block round-trips to pristine", () => {
-    const p = block(BASE, "spans two lines");
-    const cut = cutBlock(BASE, p);
-    const next = parseBlocks(cut).find((b) => b.text === "first item");
-    const restored = restoreBlock(BASE, cut, p, restoreLine(next, cut.split("\n").length));
+    // Arrange
+    const paragraph = block(BASE, "spans two lines");
+    const cut = cutBlock(BASE, paragraph);
+    const next = parseBlocks(cut).find((block) => block.text === "first item");
+
+    // Act
+    const restored = restoreBlock(BASE, cut, paragraph, restoreLine(next, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("signature rule ignores blank-line layout but not text changes", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
-    const next = parseBlocks(cut).find((b) => b.kind === "code");
+    // Arrange
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
     const line = restoreLine(next, cut.split("\n").length);
+
+    // Assert
     // extra blank lines elsewhere do not block pristine detection
-    expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), li, line)).toBeUndefined();
+    expect(
+      restoreBlock(BASE, cut.replace("## Context", "## Context\n"), listItem, line),
+    ).toBeUndefined();
     // a real text change keeps the working copy alive
-    const changed = restoreBlock(BASE, cut.replace("first", "1st"), li, line);
+    const changed = restoreBlock(BASE, cut.replace("first", "1st"), listItem, line);
+
     expect(changed).toContain("1st item");
   });
 });
 
 describe("restoreLine", () => {
   test("next surviving block's start, or the line count at the end", () => {
-    const li = block(BASE, "first item");
-    expect(restoreLine(li, 99)).toBe(li.lineStart);
+    // Arrange
+    const listItem = block(BASE, "first item");
+
+    // Assert
+    expect(restoreLine(listItem, 99)).toBe(listItem.lineStart);
     expect(restoreLine(undefined, 99)).toBe(99);
   });
 });