@camox/api-contract 0.62.0 → 0.65.1

package/src/patrol.ts

@@ -4,8 +4,11 @@
  * Live, and names each report's subject, so the studio needs no entity loaded to show it.
  */
 
-/** A patroller's stable id. The registry in the API lists them all. */
-export type PatrollerId = "translator" | "seoManager";
+/** Every patroller's stable id. The registry in the API lists them all. */
+export const PATROLLER_IDS = ["translator", "seoManager", "linkChecker", "proofreader"] as const;
+
+/** A patroller's stable id. */
+export type PatrollerId = (typeof PATROLLER_IDS)[number];
 
 /**
  * What a structured report says was done. Each has a failed form, by the report's outcome. A
@@ -16,7 +19,10 @@ export type ReportVerb =
   | "mergedWithLive"
   | "wroteSeo"
   | "describedFile"
-  | "publishedCatchUp";
+  | "publishedCatchUp"
+  | "removedLink"
+  | "fixedLink"
+  | "fixedMistake";
 
 /** What a report can be about. */
 export type ReportEntity =
@@ -51,8 +57,11 @@ export const reportLocale = (
 /** Whether the work was done, or failed. A failure shows in its report only. */
 export type ReportOutcome = "done" | "failed";
 
-/** Whether a report needs a human. Nothing raises one yet. */
-export type AttentionLevel = "none" | "needed";
+/**
+ * Where a patroller is on duty, in drafts or on Live: it works as you go, checks when you
+ * publish, or is off there (ADR 0034).
+ */
+export type PatrollerDuty = "asYouGo" | "atPublish" | "off";
 
 /**
  * Where the studio shows a report's subject: a page on the Canvas, with the block and repeatable
@@ -68,7 +77,6 @@ export type ReportView = {
   id: string;
   summary: ReportSummary;
   outcome: ReportOutcome;
-  attention: AttentionLevel;
   /** When the work last settled, in milliseconds since the epoch. */
   at: number;
   /** Whether the report is Live's, seen from a draft or from Live. */
@@ -80,6 +88,98 @@ export type ReportView = {
   place: ReportPlace | null;
 };
 
+/**
+ * What a finding is about (ADR 0034), by its kind:
+ * - `missingPage`: a link to a page that doesn't exist, the page's name as it was last known.
+ * - `brokenLink`: an external link that failed, and how.
+ * - `misspelling`, `grammar`: the flagged text, in the sentence it's in.
+ * A link's `url` is as content stores it: a page link's is `camox:page:<id>`, and `text` is what
+ * the link reads.
+ */
+export type FindingAbout =
+  | { kind: "missingPage"; url: string; text: string; page: string | null }
+  | { kind: "brokenLink"; url: string; text: string; failure: LinkFailure }
+  | { kind: "misspelling" | "grammar"; text: string; sentence: string };
+
+/** How a link failed: an HTTP error status, no connection (DNS included), or no answer in time. */
+export type LinkFailure =
+  | { kind: "status"; status: number }
+  | { kind: "unreachable" }
+  | { kind: "timeout" };
+
+export type FindingKind = FindingAbout["kind"];
+
+/**
+ * The fix a finding suggests, which applying makes: removing the link, keeping its text, or
+ * replacing the flagged text with `replacement` in its sentence, keeping its formatting.
+ */
+export type FindingFix = { kind: "removeLink" } | { kind: "replaceText"; replacement: string };
+
+/** A finding, open, in the scope viewed. */
+export type FindingView = {
+  /** What applying or dismissing it names. */
+  id: number;
+  about: FindingAbout;
+  /** The fix it suggests, if any. */
+  fix: FindingFix | null;
+  /** The content it's in, named in its locale. */
+  subject: ReportSubject;
+  /** The locale of the content it's in, by its tag. */
+  locale: string;
+  /** The content field it's in, by name. */
+  field: string;
+  /** When it was first raised, in milliseconds since the epoch. */
+  raisedAt: number;
+  /** Whether it's Live's. Live's are fixed in the Patrol Draft. */
+  live: boolean;
+  /** Where its content shows, as for reports. */
+  place: ReportPlace | null;
+};
+
+/** What a finding is about, after where it is: "links to About, a page that no longer exists". */
+function aboutSentence(about: FindingAbout): string {
+  switch (about.kind) {
+    case "missingPage":
+      return about.page === null
+        ? "links to a page that no longer exists"
+        : `links to ${about.page}, a page that no longer exists`;
+    case "brokenLink": {
+      const { failure } = about;
+      const how =
+        failure.kind === "status"
+          ? `answers with an error (${failure.status})`
+          : failure.kind === "timeout"
+            ? "doesn't answer in time"
+            : "can't be reached";
+      return `links to ${about.url}, which ${how}`;
+    }
+    case "misspelling":
+      return "may be misspelled";
+    case "grammar":
+      return "may be a grammar mistake";
+  }
+}
+
+/**
+ * A finding as one sentence, as the studio, emails, Briefs and refusals word it: "“About us” in
+ * Footer links to About, a page that no longer exists".
+ */
+export function findingSentence(finding: Pick<FindingView, "about" | "subject">): string {
+  return `“${finding.about.text}” in ${finding.subject.name} ${aboutSentence(finding.about)}`;
+}
+
+/** A member's dismissal of what a finding was about: no finding like it is raised again. */
+export type DismissalView = {
+  id: number;
+  about: FindingAbout;
+  by: { id: string; name: string };
+  /** When it was dismissed, in milliseconds since the epoch. */
+  at: number;
+};
+
+/** What applying a finding's fix did: applied it, or found its content changed and rechecked. */
+export type ApplyResult = { applied: boolean };
+
 /** How many subjects a patroller is on in one locale, a locale's tag. */
 export type LocaleCount = { locale: string; count: number };
 
@@ -96,18 +196,38 @@ export type PatrollerView = {
   id: PatrollerId;
   /** Its role, as editors know it: "Translator", "SEO manager". */
   role: string;
+  /** Its duty in the scope viewed. Off there, it still has its reports. */
+  duty: PatrollerDuty;
   /** Null when it isn't working in the scope. */
   working: PatrollerWorking | null;
-  /** Its latest activity in the scope, or null when it never worked there. */
+  /**
+   * When it last finished a check in the scope, whether it found anything or not, or null when it
+   * never checked there.
+   */
+  lastCheckedAt: number | null;
+  /**
+   * Its latest activity in the scope: its last check, its newest report or when its pending work
+   * started, whichever is later. Null when it never worked there.
+   */
   lastActivityAt: number | null;
   /** Its newest reports, newest first. */
   reports: ReportView[];
   /** How many more reports it has than `reports` shows, per locale, the most first. */
   more: { locale: string | null; count: number }[];
+  /** Its open findings in the scope viewed, the oldest first. Their count is the row's badge. */
+  findings: FindingView[];
+  /** The project's dismissals of its findings, the newest first. */
+  dismissals: DismissalView[];
 };
 
-/** Every patroller of the registry, the latest activity first; never-worked ones last. */
-export type PatrolView = { patrollers: PatrollerView[] };
+/**
+ * Every patroller of the registry, the latest activity first; never-worked ones last. With the
+ * project's open Patrol Draft, where Live's findings are fixed, if any.
+ */
+export type PatrolView = {
+  patrollers: PatrollerView[];
+  patrolDraft: { id: string; name: string | null } | null;
+};
 
 /** How many reports the Patrol shows of each patroller; the rest are counted. */
 export const REPORTS_SHOWN = 5;

package/src/threads.ts

@@ -16,6 +16,15 @@ import type { DraftOutcome } from "./drafts.ts";
  */
 export const EDITOR_MESSAGE_ENTRY = "camox.editor-message";
 
+/**
+ * The kind of the transcript entry recording a Connected Agent's message (ADR 0030), with its
+ * member and client as data (`connectedAgentMessageDataSchema`). The model reads it as a user
+ * message, as it does an editor's: its first text part is what the Connected Agent wrote, and a
+ * second one, which only the model reads, says who sent it. Studios show it as the member's AI,
+ * never as the member.
+ */
+export const CONNECTED_AGENT_MESSAGE_ENTRY = "camox.connected-agent-message";
+
 /** The kind of the transcript entry recording that an editor stopped a run, with them as data. */
 export const RUN_STOPPED_ENTRY = "camox.run-stopped";
 
@@ -36,7 +45,8 @@ export const RECONCILE_ENTRY = "camox.reconcile";
 /**
  * The kind of the transcript entry opening a draft's thread a Live thread handed a request off
  * to: the Brief, which the model reads and editors see as from Camox, ahead of the editor's
- * messages.
+ * messages. In a draft Camox opened, such as its Patrol Draft, Camox's own messages are Briefs
+ * too, with their `operationId` as data, and start the agent's run, which acts for Camox.
  */
 export const BRIEF_ENTRY = "camox.brief";
 
@@ -67,6 +77,9 @@ export const START_DRAFT_TOOL = "startDraft";
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 export const BUILD_TOOL = "build";
 
+/** The agent's tool rendering the draft in a browser and returning screenshots to the model. */
+export const LOOK_TOOL = "look";
+
 /**
  * The tools whose calls change a draft: the content tools that write, and the code tools that
  * write files. The model calls the code tools, and code mode scripts call both. A test in the API
@@ -76,6 +89,7 @@ export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
   // Content
   "addBackToLocale",
   "addLocale",
+  "applyFindingFix",
   "createBlock",
   "createCollectionRecord",
   "createPage",
@@ -132,6 +146,24 @@ export type ThreadSender = z.infer<typeof threadSenderSchema>;
 export const isSender = (data: unknown): data is ThreadSender =>
   threadSenderSchema.safeParse(data).success;
 
+/**
+ * The app a Connected Agent runs in, by the name it gave: verified when it comes from a Client ID
+ * Metadata Document, self-asserted otherwise.
+ */
+export const connectedAgentClientSchema = z.object({ name: z.string(), verified: z.boolean() });
+export type ConnectedAgentClient = z.infer<typeof connectedAgentClientSchema>;
+
+/**
+ * What a Connected Agent's message entry records: the member it acts as, its client, and the
+ * operation id it was sent with.
+ */
+export const connectedAgentMessageDataSchema = z.object({
+  member: threadSenderSchema,
+  client: connectedAgentClientSchema,
+  operationId: z.string().optional(),
+});
+export type ConnectedAgentMessageData = z.infer<typeof connectedAgentMessageDataSchema>;
+
 /** What a push's entry records: who pushed, their commits' subjects, oldest first, and the build. */
 export const pushDataSchema = z.object({
   pusher: threadSenderSchema,
@@ -205,6 +237,17 @@ export type TouchedBatch = z.infer<typeof touchedBatchSchema>;
 /** A message the studio shows in a thread. */
 export type ThreadMessage =
   | { id: string; from: "editor"; sender: ThreadSender; text: string }
+  /**
+   * A member's Connected Agent's message: the member's own AI, in its client, writing as itself.
+   * Never shown as the member's own words.
+   */
+  | {
+      id: string;
+      from: "connectedAgent";
+      member: ThreadSender;
+      client: ConnectedAgentClient;
+      text: string;
+    }
   /** Camox's own message, starting a turn it began itself: why it did. */
   | { id: string; from: "camox"; text: string }
   /** The agent's final message of a turn, in Markdown. */
@@ -236,6 +279,8 @@ export type ThreadMessage =
  * - `changing`: a call of that round changes the draft (`CHANGING_TOOLS`), as soon as it's written
  *   or, in a code mode script, as soon as the script calls one.
  * - `building`: its `build` call runs, or the end of the turn builds its code changes.
+ * - `checking`: it looks at what it designed, from writing a `look` call until the model is
+ *   called again.
  * - `fixing`: the end of the turn's build failed, and the agent fixes it.
  * - `startingDraft`: on Live, its `startDraft` call runs.
  */
@@ -244,6 +289,7 @@ export type AgentActivity =
   | "exploring"
   | "changing"
   | "building"
+  | "checking"
   | "fixing"
   | "startingDraft";
 
@@ -275,6 +321,8 @@ export type ThreadState = {
    * or making it until the model is called again.
    */
   changing?: boolean;
+  /** Whether the model's latest round calls `look`: from writing the call until it's called again. */
+  checking?: boolean;
   /** The drafts the thread's cards name, as the thread last looked them up. */
   drafts?: DraftCardStates;
 };
@@ -290,6 +338,7 @@ type ThreadStep = { id: string } & (
       /** The draft the message went to, as the agent on Live handed the request off. */
       handedOffTo?: string;
     }
+  | { type: "connectedAgent"; member: ThreadSender; client: ConnectedAgentClient; text: string }
   /** Camox starting a turn of its own, saying why. */
   | { type: "camox"; text: string }
   | { type: "answer"; text: string }
@@ -461,6 +510,18 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
         }
       );
     }
+    if (entry.kind === CONNECTED_AGENT_MESSAGE_ENTRY) {
+      const data = connectedAgentMessageDataSchema.safeParse(entry.data).data;
+      return (
+        data && {
+          id,
+          type: "connectedAgent",
+          member: senderOf(data.member)!,
+          client: { name: data.client.name, verified: data.client.verified },
+          text: editorTextOf(message.content),
+        }
+      );
+    }
     if (entry.kind === BRIEF_ENTRY) return { id, type: "camox", text: textOf(message.content) };
     if (entry.kind === RECONCILE_ENTRY) {
       const reconcile = reconcileDataSchema.safeParse(entry.data).data;
@@ -496,6 +557,7 @@ export function threadViewOf({
   toolCalls = [],
   callingTools = false,
   changing = false,
+  checking = false,
   drafts = {},
 }: ThreadState): ThreadView {
   const messages: ThreadMessage[] = [];
@@ -547,6 +609,18 @@ export function threadViewOf({
         waiting = step.id;
         break;
       }
+      case "connectedAgent":
+        // Like an editor's message: it starts a turn, or steers the one going.
+        if (unfinished) fail();
+        messages.push({
+          id: step.id,
+          from: "connectedAgent",
+          member: step.member,
+          client: step.client,
+          text: step.text,
+        });
+        waiting = step.id;
+        break;
       case "camox":
         if (unfinished) fail();
         messages.push({ id: step.id, from: "camox", text: step.text });
@@ -617,7 +691,7 @@ export function threadViewOf({
   return {
     messages,
     running,
-    activity: activityOf({ status, toolCalls, callingTools, changing }),
+    activity: activityOf({ status, toolCalls, callingTools, changing, checking }),
   };
 }
 
@@ -627,16 +701,19 @@ function activityOf({
   toolCalls,
   callingTools,
   changing,
+  checking,
 }: {
   status: BuildStatus | undefined;
   toolCalls: NonNullable<ThreadState["toolCalls"]>;
   callingTools: boolean;
   changing: boolean;
+  checking: boolean;
 }): AgentActivity {
   const calling = (name: string) => toolCalls.some((call) => call.name === name);
   // Fixing a build error takes thinking, reading and writing, which all read as fixing, but its
   // builds show as building.
   if (status === "building" || calling(BUILD_TOOL)) return "building";
+  if (checking) return "checking";
   if (status === "fixing") return "fixing";
   if (calling(START_DRAFT_TOOL)) return "startingDraft";
   if (changing) return "changing";
@@ -651,6 +728,10 @@ const changes = (name: string) => CHANGING_TOOLS.has(name);
 const callsChangingTool = (block: AssistantMessage["content"][number]) =>
   block.type === "toolCall" && changes(block.name);
 
+/** Whether a block of the model's message is a call of `look`. */
+const callsLook = (block: AssistantMessage["content"][number]) =>
+  block.type === "toolCall" && block.name === LOOK_TOOL;
+
 const append = (state: ThreadState, entry: EntryRecord | undefined): ThreadState => {
   const step = entry && threadStepOf(entry);
   if (!step || state.steps.some((known) => known.id === step.id)) return state;
@@ -671,6 +752,7 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
         running: event.run !== undefined,
         toolCalls,
         callingTools: generated.some((part) => part.type === "toolCall"),
+        checking: generated.some(callsLook) || toolCalls.some((call) => call.name === LOOK_TOOL),
         // A script's calls count while the script runs, finished or not.
         changing:
           generated.some(callsChangingTool) ||
@@ -689,11 +771,18 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
     case "run_start":
       return { ...state, running: true };
     case "run_end":
-      return { ...state, running: false, toolCalls: [], callingTools: false, changing: false };
+      return {
+        ...state,
+        running: false,
+        toolCalls: [],
+        callingTools: false,
+        changing: false,
+        checking: false,
+      };
     case "message_start":
       // The model is called again: it thinks until it writes a tool call.
       return event.message.role === "assistant"
-        ? { ...state, callingTools: false, changing: false }
+        ? { ...state, callingTools: false, changing: false, checking: false }
         : state;
     case "message_update": {
       // A call's name may come with its start, a later change to its block, or the whole message.
@@ -709,6 +798,7 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
         ...state,
         callingTools: state.callingTools || calls.some((block) => block.type === "toolCall"),
         changing: state.changing || calls.some(callsChangingTool),
+        checking: state.checking || calls.some(callsLook),
       };
     }
     case "tool_execution_start": {
@@ -717,6 +807,7 @@ export function reduceThreadState(state: ThreadState, event: AgentEvent): Thread
       return {
         ...state,
         changing,
+        checking: state.checking || event.toolName === LOOK_TOOL,
         toolCalls: [...(state.toolCalls ?? []), { callId: event.toolCallId, name: event.toolName }],
       };
     }