@cueloop/schema 0.1.0-alpha.97 → 0.1.0-alpha.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.97",
+  "version": "0.1.0-alpha.98",
   "description": "The Thread primitive: types, markdown block model, quote-primary anchors, feedback serialization",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {

package/src/agent-comment.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import { agentCommentRoot } from "./agent-comment";
+import type { ThreadAgentState } from "./thread-agent";
+
+const state: ThreadAgentState = {
+  threadId: "thread",
+  phase: { kind: "idle" },
+  messages: [],
+  tools: [],
+  comments: [],
+  submissions: [
+    { id: "prompt", commentId: "prompt", prompt: "Explain retries", status: "completed" },
+  ],
+};
+
+test("accepted bottom prompts have quote-primary read-only discussion roots", () => {
+  expect(agentCommentRoot(state, "prompt")).toMatchObject({
+    id: "prompt",
+    messageId: "prompt",
+    body: "Explain retries",
+    sent: true,
+    anchor: { quote: "Explain retries" },
+  });
+  expect(state.comments).toEqual([]);
+  expect(agentCommentRoot(state, "missing")).toBeUndefined();
+});

package/src/agent-comment.ts

@@ -0,0 +1,15 @@
+import { makeAnchor } from "./anchor";
+import { parseBlocks } from "./markdown";
+import type { AgentComment, ThreadAgentState } from "./thread-agent";
+
+/** Submitted bottom prompts are discussion roots without duplicating them in stored comments. */
+export function agentCommentRoot(state: ThreadAgentState, id: string): AgentComment | undefined {
+  const comment = state.comments.find((entry) => entry.id === id);
+  if (comment) return comment;
+  const submission = state.submissions?.find((entry) => entry.id === id && entry.commentId === id);
+  if (!submission) return undefined;
+  const blocks = parseBlocks(submission.prompt);
+  const anchor = makeAnchor(blocks, 0, 0, Math.min(blocks[0]?.text.length ?? 0, 32768));
+
+  return { id, messageId: id, anchor, body: submission.prompt.slice(0, 32768), sent: true };
+}

package/src/agent-harness.ts

@@ -0,0 +1,71 @@
+import type { AgentPermission, AgentTool, AgentConfigOption } from "./thread-agent";
+
+/** Harness events carry transcript data without exposing a provider's wire protocol. */
+export type AgentHarnessEvent =
+  | { kind: "message"; id?: string; text: string }
+  | AgentHarnessDiagnostic
+  | {
+      kind: "tool";
+      id: string;
+      title?: string;
+      toolKind?: string;
+      status?: AgentTool["status"];
+      output?: string;
+      locations?: AgentTool["locations"];
+    }
+  | { kind: "permission"; permission: AgentPermission }
+  | { kind: "config"; options: AgentConfigOption[] };
+
+/** A completed turn delivers feedback; stopped or incomplete turns preserve it for retry. */
+export interface AgentHarnessResult {
+  outcome: "completed" | "cancelled" | "incomplete";
+}
+
+/** One harness connection owns initialization, session restore, and its subprocess. */
+export interface AgentHarnessConnection {
+  start(): Promise<string>;
+  prompt(text: string): Promise<AgentHarnessResult>;
+  cancel(): void;
+  permission(requestId: string, optionId?: string): void;
+  close(): void;
+  configure?(id: string, value: string): Promise<void>;
+}
+
+/** The daemon supplies callbacks and a workspace; executable configuration stays in its adapter. */
+export interface AgentHarnessOptions {
+  cwd: string;
+  sessionId?: string;
+  tools?: AgentHarnessTools;
+  onEvent: (event: AgentHarnessEvent) => void;
+  onExit: (error: Error) => void;
+}
+
+/** A harness adapter can replace the agent runtime without changing Thread storage or rendering. */
+export interface AgentHarnessAdapter {
+  id: string;
+  label: string;
+  connect(options: AgentHarnessOptions): AgentHarnessConnection;
+}
+
+/** Tools use the daemon API; call arguments and results are serialized JSON validated at the boundary. */
+export interface AgentHarnessTools {
+  definitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+      type: "object";
+      properties: Record<string, { type: string; enum?: string[] }>;
+      required: string[];
+    };
+  }[];
+  call(name: string, args: string): Promise<string>;
+}
+
+/** Harness diagnostics never enter conversation history; unknown severities retain their spelling. */
+export interface AgentHarnessDiagnostic {
+  kind: "diagnostic";
+  severity: string;
+  title: string;
+  text: string;
+  source: "protocol" | "legacy-text";
+}

package/src/agent-input.test.ts

@@ -0,0 +1,9 @@
+import { expect, test } from "bun:test";
+import { agentInputTarget } from "./agent-input";
+
+test("typing targets a prompt, a marked comment, or neither", () => {
+  expect(agentInputTarget(true, false)).toBe("prompt");
+  expect(agentInputTarget(true, true)).toBe("prompt");
+  expect(agentInputTarget(false, true)).toBe("comment");
+  expect(agentInputTarget(false, false)).toBe("none");
+});

package/src/agent-input.ts

@@ -0,0 +1,9 @@
+/** A prompt line and a marked-text comment are mutually exclusive input targets. */
+export type AgentInputTarget = "prompt" | "comment" | "none";
+
+/** Unmarked artifact text cannot create a comment; the final prompt line never creates one. */
+export function agentInputTarget(atPrompt: boolean, hasSelection: boolean): AgentInputTarget {
+  if (atPrompt) return "prompt";
+
+  return hasSelection ? "comment" : "none";
+}

package/src/agent-submission.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test";
+import { stepAgentSubmission, type AgentSubmissionStatus } from "./agent-submission";
+
+test("an accepted submission stays locked through failure and retry", () => {
+  expect(stepAgentSubmission("draft", "submit", false)).toBe("draft");
+  let state: AgentSubmissionStatus = stepAgentSubmission("draft", "submit", true);
+
+  for (const event of ["start", "fail", "retry", "start", "complete"] as const) {
+    state = stepAgentSubmission(state, event, true);
+    expect(state).not.toBe("draft");
+    expect(stepAgentSubmission(state, "edit", true)).toBe(state);
+  }
+  expect(state).toBe("completed");
+  expect(stepAgentSubmission(state, "retry", true)).toBe("completed");
+});

package/src/agent-submission.ts

@@ -0,0 +1,38 @@
+/** Submitted comments stay read-only through queueing, completion, failure, and retry. */
+export type AgentSubmissionStatus = "draft" | "queued" | "running" | "completed" | "failed";
+
+/** Submission events never rewrite an accepted input. */
+export type AgentSubmissionEvent = "submit" | "start" | "complete" | "fail" | "retry" | "edit";
+
+/** Empty input cannot create a turn; retry is valid only for a failed submission. */
+export function stepAgentSubmission(status: "draft", event: "submit", hasInput: true): "queued";
+export function stepAgentSubmission(
+  status: Exclude<AgentSubmissionStatus, "draft">,
+  event: AgentSubmissionEvent,
+  hasInput: boolean,
+): Exclude<AgentSubmissionStatus, "draft">;
+export function stepAgentSubmission(
+  status: AgentSubmissionStatus,
+  event: AgentSubmissionEvent,
+  hasInput: boolean,
+): AgentSubmissionStatus;
+export function stepAgentSubmission(
+  status: AgentSubmissionStatus,
+  event: AgentSubmissionEvent,
+  hasInput: boolean,
+): AgentSubmissionStatus {
+  switch (event) {
+    case "submit":
+      return status === "draft" && hasInput ? "queued" : status;
+    case "start":
+      return status === "queued" ? "running" : status;
+    case "complete":
+      return status === "running" ? "completed" : status;
+    case "fail":
+      return status === "running" ? "failed" : status;
+    case "retry":
+      return status === "failed" ? "queued" : status;
+    case "edit":
+      return status;
+  }
+}

package/src/harness-output-routing.test.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+import { routeHarnessOutput } from "./harness-output-routing";
+
+test("identical assistant and diagnostic wording takes different destinations", () => {
+  const text =
+    "[context] skill catalog shortened 112 descriptions: effective=20480 bytes source=compiled default\n";
+
+  expect(routeHarnessOutput({ kind: "message", text }).destination).toBe("thread");
+  expect(
+    routeHarnessOutput({
+      kind: "diagnostic",
+      text,
+      severity: "future-severity",
+      title: "Notice",
+      source: "protocol",
+    }).destination,
+  ).toBe("diagnostics");
+});

package/src/harness-output-routing.ts

@@ -0,0 +1,12 @@
+import type { AgentHarnessDiagnostic, AgentHarnessEvent } from "./agent-harness";
+
+type RoutedHarnessOutput =
+  | { destination: "diagnostics"; event: AgentHarnessDiagnostic }
+  | { destination: "thread"; event: Exclude<AgentHarnessEvent, AgentHarnessDiagnostic> };
+
+/** Route normalized harness output by provenance; assistant wording never changes its destination. */
+export function routeHarnessOutput(event: AgentHarnessEvent): RoutedHarnessOutput {
+  if (event.kind === "diagnostic") return { destination: "diagnostics", event };
+
+  return { destination: "thread", event };
+}

package/src/index.ts

@@ -13,3 +13,13 @@ export * from "./herdr";
 export * from "./thread-surface";
 export * from "./history";
 export * from "./path-view";
+export * from "./thread-agent";
+export * from "./agent-harness";
+
+export * from "./agent-submission";
+
+export { agentCommentRoot } from "./agent-comment";
+
+export * from "./agent-input";
+
+export * from "./harness-output-routing";

package/src/thread-agent.ts

@@ -0,0 +1,80 @@
+import type { Anchor } 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;
+  /** Session identity is bound to its adapter; another harness cannot resume it. */
+  harness?: { id: string; label: string; sessionId?: string };
+  phase: AgentPhase;
+  messages: AgentMessage[];
+  tools: AgentTool[];
+  comments: AgentComment[];
+  submissions?: AgentSubmission[];
+  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";
+}
+
+/** 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 }[];
+}