@camox/api-contract 0.72.0 → 0.75.0

package/src/{patrol.ts → specialists.ts}

@@ -1,14 +1,14 @@
 /**
- * The Patrol (ADR 0024): every patroller of a project, the work each did as reports, as the
+ * The Specialists (ADR 0024): every specialist of a project, the work each did as reports, as the
  * studio shows it at the top of the Agent Sidebar. The API reads it for one scope, a draft or
  * Live, and names each report's subject, so the studio needs no entity loaded to show it.
  */
 
-/** Every patroller's stable id. The registry in the API lists them all. */
-export const PATROLLER_IDS = ["translator", "seoManager", "linkChecker"] as const;
+/** Every specialist's stable id. The registry in the API lists them all. */
+export const SPECIALIST_IDS = ["translator", "seoManager", "linkChecker"] as const;
 
-/** A patroller's stable id. */
-export type PatrollerId = (typeof PATROLLER_IDS)[number];
+/** A specialist's stable id. */
+export type SpecialistId = (typeof SPECIALIST_IDS)[number];
 
 /**
  * What a structured report says was done. Each has a failed form, by the report's outcome. A
@@ -32,7 +32,7 @@ export type ReportEntity =
   | "record"
   | "file";
 
-/** A report's subject, named as the Canvas names it, read when the Patrol is. */
+/** A report's subject, named as the Canvas names it, read when the Specialists is. */
 export type ReportSubject = { entity: ReportEntity; id: string; name: string };
 
 /**
@@ -57,10 +57,10 @@ export const reportLocale = (
 export type ReportOutcome = "done" | "failed";
 
 /**
- * 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).
+ * Where a specialist is on duty, in drafts or on Live: it works as you go, or is off there (ADR
+ * 0034). None checks when you publish: publishing never waits on Camox (ADR 0043).
  */
-export type PatrollerDuty = "asYouGo" | "atPublish" | "off";
+export type SpecialistDuty = "asYouGo" | "off";
 
 /**
  * Where the studio shows a report's subject: a page on the Canvas, with the block and repeatable
@@ -72,7 +72,7 @@ export type ReportPlace =
   | { kind: "file"; fileId: string };
 
 export type ReportView = {
-  /** Unique among the patroller's reports in the view. */
+  /** Unique among the specialist's reports in the view. */
   id: string;
   summary: ReportSummary;
   outcome: ReportOutcome;
@@ -91,12 +91,14 @@ export type ReportView = {
  * 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.
+ * - `missingMetaTitle`: a page whose meta title is written by hand, and empty.
  * 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: "brokenLink"; url: string; text: string; failure: LinkFailure }
+  | { kind: "missingMetaTitle" };
 
 /** How a link failed: an HTTP error status, no connection (DNS included), or no answer in time. */
 export type LinkFailure =
@@ -126,14 +128,17 @@ export type FindingView = {
   fieldKind: string | null;
   /** 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. */
+  /**
+   * Whether it's Live's. A draft shows Live's findings on the content it still holds, and fixes
+   * them there.
+   */
   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 {
+/** What a link finding is about, after where it is: "links to About, a page that no longer exists". */
+function linkSentence(about: Exclude<FindingAbout, { kind: "missingMetaTitle" }>): string {
   switch (about.kind) {
     case "missingPage":
       return about.page === null
@@ -154,10 +159,12 @@ function aboutSentence(about: FindingAbout): string {
 
 /**
  * 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".
+ * Footer links to About, a page that no longer exists", or "Pricing has no meta title".
  */
 export function findingSentence(finding: Pick<FindingView, "about" | "subject">): string {
-  return `“${finding.about.text}” in ${finding.subject.name} ${aboutSentence(finding.about)}`;
+  const { about, subject } = finding;
+  if (about.kind === "missingMetaTitle") return `${subject.name} has no meta title`;
+  return `“${about.text}” in ${subject.name} ${linkSentence(about)}`;
 }
 
 /**
@@ -165,7 +172,9 @@ export function findingSentence(finding: Pick<FindingView, "about" | "subject">)
  * by its field: "“About us” links to About, a page that no longer exists".
  */
 export function findingSentenceInPlace(finding: Pick<FindingView, "about">): string {
-  return `“${finding.about.text}” ${aboutSentence(finding.about)}`;
+  const { about } = finding;
+  if (about.kind === "missingMetaTitle") return "The page has no meta title";
+  return `“${about.text}” ${linkSentence(about)}`;
 }
 
 /** A member's dismissal of what a finding was about: no finding like it is raised again. */
@@ -180,26 +189,26 @@ export type DismissalView = {
 /** 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. */
+/** How many subjects a specialist is on in one locale, a locale's tag. */
 export type LocaleCount = { locale: string; count: number };
 
 /**
- * What a patroller is on: the one subject when there's one, and how many subjects in each
+ * What a specialist is on: the one subject when there's one, and how many subjects in each
  * locale, the most first. A subject in several locales counts in each.
  */
-export type PatrollerWorking = {
+export type SpecialistWorking = {
   subject: ReportSubject | null;
   locales: LocaleCount[];
 };
 
-export type PatrollerView = {
-  id: PatrollerId;
+export type SpecialistView = {
+  id: SpecialistId;
   /** 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;
+  duty: SpecialistDuty;
   /** Null when it isn't working in the scope. */
-  working: PatrollerWorking | null;
+  working: SpecialistWorking | null;
   /**
    * When it last finished a check in the scope, whether it found anything or not, or null when it
    * never checked there.
@@ -220,14 +229,14 @@ export type PatrollerView = {
   dismissals: DismissalView[];
 };
 
+/** Every specialist of the registry, the latest activity first; never-worked ones last. */
+export type SpecialistsView = { specialists: SpecialistView[] };
+
 /**
- * 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.
+ * URL search param the studio opens a specialist's findings from, by its id, as the email about
+ * Live's new findings links to them. The studio drops it once opened.
  */
-export type PatrolView = {
-  patrollers: PatrollerView[];
-  patrolDraft: { id: string; name: string | null } | null;
-};
+export const SPECIALIST_SEARCH_PARAM = "camox-specialist";
 
-/** How many reports the Patrol shows of each patroller; the rest are counted. */
+/** How many reports the Specialists shows of each specialist; the rest are counted. */
 export const REPORTS_SHOWN = 5;

package/src/threads.ts

@@ -45,8 +45,7 @@ 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 ahead of the editor's messages, and editors see collapsed
- * after them, so the request reads on as they sent it. 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.
+ * after them, so the request reads on as they sent it.
  */
 export const BRIEF_ENTRY = "camox.brief";
 
@@ -127,6 +126,30 @@ export const codeRequestDataSchema = artifactRequestDataSchema.extend({
 });
 export type CodeRequestData = z.infer<typeof codeRequestDataSchema>;
 
+/**
+ * The draft thread's agent's tool asking the Connected Agents following its turn questions, which
+ * their waiting calls come back with as the agent works on (ADR 0042). The model calls it itself,
+ * never from a script.
+ */
+export const ASK_TOOL = "askConnectedAgent";
+
+/**
+ * The kind of the transcript entry recording questions the agent asked the Connected Agents
+ * following its turn, with a `questionsDataSchema` as data. Neither the model nor editors read
+ * it: questions are never a thread's messages, and never end its turn.
+ */
+export const QUESTIONS_ENTRY = "camox.questions";
+
+/**
+ * What a questions entry records: the questions, in the order the agent asked them, and the
+ * Connected Agents they were asked of, each by its member's id and client id.
+ */
+export const questionsDataSchema = z.object({
+  questions: z.array(z.string()).min(1),
+  to: z.array(z.object({ memberId: z.string(), clientId: z.string() })),
+});
+export type QuestionsData = z.infer<typeof questionsDataSchema>;
+
 /**
  * The agent's tools handing work to an agent of its own, in a conversation beside the thread's,
  * whose answer they return: editors see what that agent does as the agent's.
@@ -209,14 +232,26 @@ export const isSender = (data: unknown): data is ThreadSender =>
 export const connectedAgentClientSchema = z.object({ name: z.string(), verified: z.boolean() });
 export type ConnectedAgentClient = z.infer<typeof connectedAgentClientSchema>;
 
+/** An Attachment a Connected Agent's message carries: an image the agent sees with it. */
+export const messageAttachmentSchema = z.object({
+  id: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  url: z.string(),
+});
+export type MessageAttachmentData = z.infer<typeof messageAttachmentSchema>;
+
 /**
- * What a Connected Agent's message entry records: the member it acts as, its client, and the
- * operation id it was sent with.
+ * What a Connected Agent's message entry records: the member it acts as, its client, the
+ * operation id it was sent with, and whether it answers the agent's questions (ADR 0042).
  */
 export const connectedAgentMessageDataSchema = z.object({
   member: threadSenderSchema,
   client: connectedAgentClientSchema,
   operationId: z.string().optional(),
+  answer: z.boolean().optional(),
+  /** The images the message carries for the agent to see, as studios list them (ADR 0044). */
+  attachments: z.array(messageAttachmentSchema).optional(),
 });
 export type ConnectedAgentMessageData = z.infer<typeof connectedAgentMessageDataSchema>;
 
@@ -291,7 +326,9 @@ 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.
+   * Never shown as the member's own words. An answer to the agent's questions shows as the
+   * context the draft was built on, collapsed, as a Brief does, rather than as a request
+   * (ADR 0042).
    */
   | {
       id: string;
@@ -299,6 +336,9 @@ export type ThreadMessage =
       member: ThreadSender;
       client: ConnectedAgentClient;
       text: string;
+      answer: boolean;
+      /** The images it carries for the agent to see, if any (ADR 0044). */
+      attachments?: MessageAttachmentData[];
     }
   /** Camox's own message, starting a turn it began itself: why it did. */
   | { id: string; from: "camox"; text: string }
@@ -408,7 +448,14 @@ export const EMPTY_THREAD_STATE: ThreadState = { steps: [], running: false };
 /** One transcript entry, as far as the studio's view is concerned. */
 type ThreadStep = { id: string } & (
   | { type: "editor"; sender: ThreadSender; text: string }
-  | { type: "connectedAgent"; member: ThreadSender; client: ConnectedAgentClient; text: string }
+  | {
+      type: "connectedAgent";
+      member: ThreadSender;
+      client: ConnectedAgentClient;
+      text: string;
+      answer: boolean;
+      attachments?: MessageAttachmentData[];
+    }
   /** Camox starting a turn of its own, saying why. */
   | { type: "camox"; text: string }
   /** The Brief opening a draft's thread a Live thread handed a request off to. */
@@ -584,6 +631,8 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
           member: senderOf(data.member)!,
           client: { name: data.client.name, verified: data.client.verified },
           text: editorTextOf(message.content),
+          answer: data.answer ?? false,
+          ...(data.attachments?.length && { attachments: data.attachments }),
         }
       );
     }
@@ -687,6 +736,8 @@ export function threadViewOf({
           member: step.member,
           client: step.client,
           text: step.text,
+          answer: step.answer,
+          ...(step.attachments && { attachments: step.attachments }),
         });
         waiting = step.id;
         break;