@skillcdn/console 0.1.15 → 0.1.17

package/src/components/event-feed.tsx

@@ -76,6 +76,8 @@ export function describeEvent(event: RestEvent, words: Messages = en): string {
       );
     case "task.updated":
       return feed.event.taskUpdated(fields, task);
+    case "task.commented":
+      return feed.event.taskCommented(task, data.excerpt);
     case "decision.raised":
       return feed.event.decisionRaised(question);
     case "decision.answered":

package/src/components/markdown.tsx

@@ -14,6 +14,12 @@ export interface MarkdownProps {
   readonly source: string;
   /** Where a document of the project is read, by its path; left out, such links stay text. */
   readonly docHref?: ((path: string) => string) | undefined;
+  /**
+   * Where a picture named in the text is read, when the text comes with files: given the
+   * source of `![words](source)`, the address of the file it names, or nothing. A picture that
+   * is neither one of those nor over https stays text.
+   */
+  readonly fileSrc?: ((source: string) => string | undefined) | undefined;
 }
 
 export function Markdown(props: MarkdownProps) {
@@ -48,7 +54,9 @@ export function Markdown(props: MarkdownProps) {
             return <span>{children}</span>;
           },
           img({ src, alt, title }) {
-            const url = typeof src === "string" && SAFE_IMAGE.test(src) ? src : undefined;
+            const named = typeof src === "string" ? props.fileSrc?.(src) : undefined;
+            const url =
+              named ?? (typeof src === "string" && SAFE_IMAGE.test(src) ? src : undefined);
             if (url === undefined) {
               return <span className="sc-prose-image-text">{alt ?? ""}</span>;
             }

package/src/components/projects.tsx

@@ -25,7 +25,10 @@ import {
 import { useWords } from "../i18n/index.js";
 import { Badge, Button, cx, PersonChip, personName, Time } from "./ui.js";
 
-/** A project's mark: its symbol on its colour, so that projects tell apart at a glance. */
+/**
+ * A project's mark: its symbol on its colour, so that projects tell apart at a glance; its own
+ * image over the symbol where it has one, so that the mark is never empty while the image loads.
+ */
 export function ProjectMark(props: {
   readonly project: {
     readonly key: string;
@@ -43,20 +46,30 @@ export function ProjectMark(props: {
   const icon = props.project.icon ?? null;
   const src =
     props.iconSrc ?? (icon === null ? undefined : projectIconPath(props.project.key, icon));
+  // The symbol stands in until the image is there, and comes back should the image fail; once
+  // the image is shown, the symbol goes, since an image with clear parts would show it through.
+  const [shown, setShown] = useState<string | undefined>(undefined);
+  const [failed, setFailed] = useState<string | undefined>(undefined);
+  const pictured = src !== undefined && failed !== src;
   return (
     <span
       className={cx(
         "sc-mark",
         `sc-mark-${size}`,
         `sc-category-${projectColorOf(props.project)}`,
-        src !== undefined && "sc-mark-pictured",
+        pictured && "sc-mark-pictured",
       )}
       aria-hidden="true"
     >
-      {src === undefined ? (
-        projectSymbolOf(props.project)
-      ) : (
-        <img className="sc-mark-image" src={src} alt="" />
+      {(!pictured || shown !== src) && projectSymbolOf(props.project)}
+      {pictured && (
+        <img
+          className="sc-mark-image"
+          src={src}
+          alt=""
+          onLoad={() => setShown(src)}
+          onError={() => setFailed(src)}
+        />
       )}
     </span>
   );

package/src/components/task-form.tsx

@@ -96,6 +96,7 @@ export function TaskForm(props: TaskFormProps) {
         <input
           className="sc-input"
           value={title}
+          placeholder={form.titlePlaceholder}
           maxLength={MAX_TITLE_LENGTH}
           required
           onChange={(event) => setTitle(event.target.value)}

package/src/components/task-view.tsx

@@ -1,7 +1,7 @@
 import type {
   RestAnswerInput,
-  RestArtifact,
   RestCategory,
+  RestComment,
   RestDecision,
   RestDecisionInput,
   RestDecisionPatch,
@@ -17,19 +17,20 @@ import { formatDay } from "../dates.js";
 import { useLanguage, useWords } from "../i18n/index.js";
 import type { TaskFormKind } from "../router.js";
 import { TASK_STATES } from "../vocabulary.js";
+import { type CommentDraft, TaskThread } from "./comments.js";
 import { DecisionForm } from "./decision-form.js";
-import { DecisionCard } from "./decision-list.js";
 import { EventFeed } from "./event-feed.js";
 import { Markdown } from "./markdown.js";
-import { RunList } from "./runs.js";
 import { TaskForm } from "./task-form.js";
 import { CategoryBadge, DueBadge, PersonChip, PriorityBadge, StateBadge, Time } from "./ui.js";
 
-// One task: what it is, who it is on, what it links to, the agents at work on it, the decisions
-// about it, the tasks that are part of it, everything that happened to it, and the ways to
-// change it. Takes its data as props and nothing from the network; which of its forms is open
-// is told by the page, since each form has an address of its own (ADR-0010). The facts beside
-// the text say only what is set: a plan, a category or a goal the task has none of is not a row.
+// One task: what it is, who it is on, what it links to, the discussion on it, which is what was
+// said about it with the agents at work on it and the decisions about it in the order they
+// came (ADR-0024), the tasks that are part of it, everything that happened to it, and the ways
+// to change it. Takes its data as props and nothing from the network; which of its forms is
+// open is told by the page, since each form has an address of its own (ADR-0010). The facts
+// beside the text say only what is set: a plan, a category or a goal the task has none of is
+// not a row.
 
 export interface TaskViewProps {
   readonly task: RestTask;
@@ -39,6 +40,8 @@ export interface TaskViewProps {
   readonly decisions: readonly RestDecision[];
   /** The runs of the board, or of this task; the ones on this task are shown. */
   readonly runs?: readonly RestRun[] | undefined;
+  /** The comments on the task, oldest first, when the page has read them. */
+  readonly comments?: readonly RestComment[] | undefined;
   /** Everything that happened to the task, oldest first, when the page has read it. */
   readonly history?: readonly RestEvent[] | undefined;
   /** The categories of the workspace, for the form. */
@@ -50,8 +53,8 @@ export interface TaskViewProps {
   readonly decisionHref?: ((decisionId: string) => string) | undefined;
   /** Where a goal of the roadmap is read. */
   readonly goalHref?: ((goalId: string) => string) | undefined;
-  /** Where a file a run handed in is read. */
-  readonly fileHref?: ((artifact: RestArtifact) => string) | undefined;
+  /** Where a file of the project is read, by its id: one a run handed in, or one put in a comment. */
+  readonly fileHref?: ((fileId: string) => string) | undefined;
   /** Where a document of the project is read, by its path, for the links in what was written. */
   readonly docHref?: ((path: string) => string) | undefined;
   /** The day to count due days from; the browser's today when left out. */
@@ -73,6 +76,8 @@ export interface TaskViewProps {
     | ((decision: RestDecision, patch: RestDecisionPatch) => void)
     | undefined;
   readonly onAbandonRun?: ((run: RestRun) => void) | undefined;
+  /** Called with a word for the discussion, and the files put in it. Left out, nothing can be said here. */
+  readonly onComment?: ((draft: CommentDraft) => void) | undefined;
 }
 
 export function TaskView(props: TaskViewProps) {
@@ -86,7 +91,7 @@ export function TaskView(props: TaskViewProps) {
   const subtasks = props.tasks.filter((candidate) => candidate.parentId === task.id);
   const about = props.decisions.filter((decision) => decision.taskId === task.id);
   const runs = (props.runs ?? []).filter((run) => run.taskId === task.id);
-  const tasksById = new Map(props.tasks.map((candidate) => [candidate.id, candidate]));
+  const comments = (props.comments ?? []).filter((comment) => comment.taskId === task.id);
   const goal =
     task.goalId === null
       ? undefined
@@ -175,35 +180,29 @@ export function TaskView(props: TaskViewProps) {
               />
             </section>
           )}
-          {runs.length > 0 && (
-            <section className="sc-task-section" aria-label={words.task.runs}>
-              <h2 className="sc-section-title">{words.task.runs}</h2>
-              <RunList
+          {(runs.length > 0 ||
+            about.length > 0 ||
+            comments.length > 0 ||
+            props.onComment !== undefined) && (
+            <section className="sc-task-section" aria-label={words.comments.title}>
+              <h2 className="sc-section-title">{words.comments.title}</h2>
+              <TaskThread
+                task={task}
+                comments={comments}
                 runs={runs}
-                decisionHref={props.decisionHref}
+                decisions={about}
                 fileHref={props.fileHref}
+                decisionHref={props.decisionHref}
                 docHref={props.docHref}
-                onAbandon={props.onAbandonRun}
+                onAnswer={props.onAnswer}
+                onUpdateDecision={props.onUpdateDecision}
+                onAbandonRun={props.onAbandonRun}
+                onComment={props.onComment}
                 busy={props.busy}
+                empty={<p className="sc-muted">{words.comments.empty}</p>}
               />
             </section>
           )}
-          {about.length > 0 && (
-            <section className="sc-task-section" aria-label={words.task.decisions}>
-              <h2 className="sc-section-title">{words.task.decisions}</h2>
-              {about.map((decision) => (
-                <DecisionCard
-                  key={decision.id}
-                  decision={decision}
-                  task={decision.taskId === null ? undefined : tasksById.get(decision.taskId)}
-                  docHref={props.docHref}
-                  onAnswer={props.onAnswer}
-                  onUpdate={props.onUpdateDecision}
-                  busy={props.busy}
-                />
-              ))}
-            </section>
-          )}
           {props.history !== undefined && props.history.length > 0 && (
             <section className="sc-task-section" aria-label={words.task.history}>
               <h2 className="sc-section-title">{words.task.history}</h2>

package/src/console.tsx

@@ -17,6 +17,7 @@ import {
   PROJECT_RULES_TEMPLATE,
   REFERENCE_RULES,
   type RestAnswerInput,
+  type RestComment,
   type RestDecision,
   type RestDecisionInput,
   type RestDecisionPatch,
@@ -457,7 +458,8 @@ function TaskPage(props: {
       ? data.tasks.find((candidate) => candidate.id === route.id)
       : data.tasks.find((candidate) => candidate.number === route.number);
   const [history, setHistory] = useState<readonly RestEvent[] | undefined>(undefined);
-  const { taskHistory } = data.actions;
+  const [comments, setComments] = useState<readonly RestComment[] | undefined>(undefined);
+  const { taskHistory, taskComments } = data.actions;
   const taskId = task?.id;
   const number = task?.number;
   // A task named by its id is shown at its number's address.
@@ -481,8 +483,15 @@ function TaskPage(props: {
         }
       })
       .catch(() => undefined);
+    taskComments(taskId, controller.signal)
+      .then((items) => {
+        if (!controller.signal.aborted) {
+          setComments(items);
+        }
+      })
+      .catch(() => undefined);
     return () => controller.abort();
-  }, [taskId, taskHistory, feedLength]);
+  }, [taskId, taskHistory, taskComments, feedLength]);
   if (task === undefined) {
     return (
       <EmptyState
@@ -500,13 +509,14 @@ function TaskPage(props: {
       tasks={data.tasks}
       decisions={data.decisions}
       runs={data.runs}
+      comments={comments}
       history={history}
       categories={data.categories}
       goals={data.goals}
       taskHref={(candidate) => taskHref(key, candidate.number)}
       decisionHref={(decisionId) => decisionHref(key, decisionId)}
       goalHref={(goalId) => goalHref(key, goalId)}
-      fileHref={(artifact) => projectPath(key, "files", artifact.id)}
+      fileHref={(fileId) => projectPath(key, "files", fileId)}
       docHref={(path) => docHref(key, path)}
       form={route.form}
       formHref={(form) => taskHref(key, task.number, form)}
@@ -533,6 +543,19 @@ function TaskPage(props: {
         void act(() => data.actions.updateDecision(decision.id, patch))
       }
       onAbandonRun={(run) => void act(() => data.actions.abandonRun(run.id))}
+      onComment={(draft) =>
+        void act(async () => {
+          await data.actions.comment(task.id, {
+            body: draft.body,
+            files: draft.files.map((file) => ({
+              name: file.name,
+              bytes: file,
+              ...(file.type === "" ? {} : { contentType: file.type }),
+            })),
+          });
+          setComments(await taskComments(task.id));
+        })
+      }
     />
   );
 }
@@ -677,6 +700,7 @@ function ProjectPage(props: {
           month={month}
           today={now}
           categories={data.categories}
+          goals={data.goals}
           taskHref={href}
           monthHref={(wanted) => calendarHref(key, wanted, route.filter)}
         />

package/src/data.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   ApiError,
+  type CommentInput,
   type ConsoleClient,
   type DocumentFilter,
   EVENT_KINDS,
@@ -9,6 +10,7 @@ import {
   type RestCategory,
   type RestCategoryInput,
   type RestCategoryPatch,
+  type RestComment,
   type RestConnectRequest,
   type RestDecision,
   type RestDecisionInput,
@@ -117,6 +119,10 @@ export interface ConsoleActions {
   abandonRun(id: string): Promise<RestRun>;
   /** Everything that happened to one task of the project, oldest first. */
   taskHistory(taskId: string, signal?: AbortSignal): Promise<RestEvent[]>;
+  /** The discussion on one task of the project, oldest first (ADR-0024). */
+  taskComments(taskId: string, signal?: AbortSignal): Promise<RestComment[]>;
+  /** A word in the discussion on a task, with the files put in it. */
+  comment(taskId: string, input: CommentInput): Promise<RestComment>;
   /** Makes a token for whoever is signed in; the answer carries the secret, this once. */
   createToken(input: RestTokenInput): Promise<RestTokenCreated>;
   revokeToken(id: string): Promise<void>;
@@ -560,6 +566,8 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
         }
         return history;
       },
+      taskComments: async (taskId, signal) => (await scope().comments(taskId, signal)).items,
+      comment: (taskId, input) => scope().comment(taskId, input),
       async createToken(input) {
         const made = await client.createToken(input);
         setTokens((await client.tokens()).items);

package/src/i18n/en.ts

@@ -131,7 +131,7 @@ export const en = {
   },
 
   signIn: {
-    lead: "The board of the work, the agents at it, what they did, and the decisions that wait for a person.",
+    lead: "Join an organization made of AI agents.",
     continueWith: (provider: string) => `Continue with ${provider}`,
     nobody: {
       title: "Nobody can sign in here yet",
@@ -249,8 +249,6 @@ export const en = {
     raiseDecision: "Raise a decision",
     nothingMore: "Nothing more was written about it.",
     links: "Links",
-    runs: "Runs",
-    decisions: "Decisions",
     history: "What happened",
     subtasks: "Subtasks",
     partOfIt: "Part of it",
@@ -269,6 +267,7 @@ export const en = {
     done: "Done",
     form: {
       title: "Title",
+      titlePlaceholder: "What is to be done, in plain words that stand on their own.",
       body: "Body",
       bodyPlaceholder: "What is to be done, in Markdown.",
       state: "State",
@@ -299,7 +298,7 @@ export const en = {
       body: "It may belong to another project, or the link is wrong.",
     },
     empty: {
-      title: "Nothing waits for a person",
+      title: "No decision waits for a person",
       body: "A decision raised from a task, or from here, shows up on this page.",
     },
     waiting: "Waiting",
@@ -537,6 +536,8 @@ export const en = {
       taskCreated: (task: string) => `wrote ${task}`,
       taskMoved: (task: string, from: string, to: string) => `moved ${task} from ${from} to ${to}`,
       taskUpdated: (fields: string, task: string) => `changed ${fields} of ${task}`,
+      taskCommented: (task: string, excerpt: string | undefined) =>
+        `commented on ${task}${excerpt === undefined || excerpt === "" ? "" : `: ${excerpt}`}`,
       decisionRaised: (question: string) => `asked: ${question}`,
       decisionAnswered: (question: string, option: string) => `answered "${question}": ${option}`,
       decisionUpdated: (fields: string, question: string) =>
@@ -570,6 +571,20 @@ export const en = {
     label: (agent: string, name: string) => `${agent} for ${name}`,
   },
 
+  comments: {
+    title: "Discussion",
+    empty: "Nothing was said yet.",
+    one: "Comment",
+    write: "Write a comment",
+    placeholder: "A word in the discussion, in Markdown.",
+    files: "Files",
+    chooseFiles: "Add files",
+    hint: "A picture pasted or chosen here goes with the comment; ![words](its name) places it in the text.",
+    removeFile: (name: string) => `Take ${name} out`,
+    picture: (name: string) => `The picture ${name}`,
+    label: (name: string) => `A comment by ${name}`,
+  },
+
   skills: {
     loading: "Loading the skills",
     list: "Skills",

package/src/i18n/ko.ts

@@ -101,7 +101,7 @@ export const ko: Messages = {
   },
 
   signIn: {
-    lead: "할 일의 보드, 일하는 에이전트, 그들이 한 일, 그리고 사람을 기다리는 결정.",
+    lead: "AI 에이전트로 이뤄진 조직에 합류하세요.",
     continueWith: (provider) => `${provider}로 계속`,
     nobody: {
       title: "아직 아무도 로그인할 수 없습니다",
@@ -218,8 +218,6 @@ export const ko: Messages = {
     raiseDecision: "결정 요청",
     nothingMore: "더 적힌 내용이 없습니다.",
     links: "링크",
-    runs: "실행",
-    decisions: "결정",
     history: "일어난 일",
     subtasks: "하위 작업",
     partOfIt: "하위 작업",
@@ -238,6 +236,7 @@ export const ko: Messages = {
     done: "완료",
     form: {
       title: "제목",
+      titlePlaceholder: "무엇을 할지, 제목만 보고도 알 수 있게.",
       body: "본문",
       bodyPlaceholder: "무엇을 할지, Markdown으로.",
       state: "상태",
@@ -268,7 +267,7 @@ export const ko: Messages = {
       body: "다른 프로젝트의 것이거나, 링크가 잘못됐습니다.",
     },
     empty: {
-      title: "사람을 기다리는 것이 없습니다",
+      title: "사람을 기다리는 결정이 없습니다",
       body: "작업에서, 또는 여기서 요청한 결정이 이 페이지에 나타납니다.",
     },
     waiting: "대기 중",
@@ -503,6 +502,8 @@ export const ko: Messages = {
       taskCreated: (task) => `${task}을(를) 썼습니다`,
       taskMoved: (task, from, to) => `${task}을(를) ${from}에서 ${to}(으)로 옮겼습니다`,
       taskUpdated: (fields, task) => `${task}의 ${fields}을(를) 바꿨습니다`,
+      taskCommented: (task, excerpt) =>
+        `${task}에 댓글을 남겼습니다${excerpt === undefined || excerpt === "" ? "" : `: ${excerpt}`}`,
       decisionRaised: (question) => `질문했습니다: ${question}`,
       decisionAnswered: (question, option) => `"${question}"에 답했습니다: ${option}`,
       decisionUpdated: (fields, question) => `결정 "${question}"의 ${fields}을(를) 썼습니다`,
@@ -535,6 +536,20 @@ export const ko: Messages = {
     label: (agent, name) => `${name}을(를) 위한 ${agent}`,
   },
 
+  comments: {
+    title: "논의",
+    empty: "아직 아무 말도 없습니다.",
+    one: "댓글 남기기",
+    write: "댓글 쓰기",
+    placeholder: "논의에 보탤 말을 마크다운으로.",
+    files: "파일",
+    chooseFiles: "파일 추가",
+    hint: "여기에 붙여 넣거나 고른 그림은 댓글과 함께 올라갑니다. ![설명](파일 이름)으로 본문에 넣을 수 있습니다.",
+    removeFile: (name) => `${name} 빼기`,
+    picture: (name) => `그림 ${name}`,
+    label: (name) => `${name}의 댓글`,
+  },
+
   skills: {
     loading: "스킬을 불러오는 중",
     list: "스킬",

package/src/index.ts

@@ -26,6 +26,18 @@ export {
   workloadOf,
 } from "./components/calendar.js";
 export { CategoryList, type CategoryListProps } from "./components/categories.js";
+export {
+  CommentCard,
+  type CommentCardProps,
+  type CommentDraft,
+  CommentForm,
+  type CommentFormProps,
+  isPicture,
+  TaskThread,
+  type TaskThreadProps,
+  type ThreadItem,
+  threadOf,
+} from "./components/comments.js";
 export {
   ConnectApproval,
   type ConnectApprovalProps,

package/src/limits.ts

@@ -28,6 +28,9 @@ export const MAX_SUMMARY_LENGTH = 2000;
 /** How many reports, and how many artifacts, one run may carry. */
 export const MAX_REPORTS_PER_RUN = 500;
 export const MAX_ARTIFACTS_PER_RUN = 50;
+/** How many comments one task carries, and how many files one comment carries, together within `MAX_FILE_BYTES`. */
+export const MAX_COMMENTS_PER_TASK = 500;
+export const MAX_FILES_PER_COMMENT = 10;
 /** A file a run hands in: how many bytes, and its name, one line without a path. */
 export const MAX_FILE_BYTES = 10 * 1024 * 1024;
 export const MAX_FILE_NAME_LENGTH = 200;

package/src/rules.ts

@@ -23,7 +23,7 @@ export const REFERENCE_RULES = [
   "",
   "## Start here, every time",
   "",
-  "1. These rules come with the task: `console take` prints them under it, and `console rules` reads them any time. Read them before anything is made. The task says where the work is and what it links to; `console task <number>` shows a task in full, with its plan, its decisions and the runs on it, without taking it. How the board is worked is the skill working-the-board, shipped with the command (`console skills` says where it is); these rules say what this organization asks, not how the command works.",
+  "1. These rules come with the task: `console take` prints them under it, and `console rules` reads them any time. Read them before anything is made. The task says where the work is and what it links to; `console task <number>` shows a task in full, with its plan, its decisions, the runs on it and the discussion on it, without taking it. How the board is worked is the skill working-the-board, shipped with the command (`console skills` says where it is); these rules say what this organization asks, not how the command works.",
   "2. Act as the person whose token the command holds, and no further. What they may not do, the console refuses; that step goes back to them in a report, never around them.",
   "",
   "## The organization's skills",
@@ -44,7 +44,7 @@ export const REFERENCE_RULES = [
   "",
   "## Reports",
   "",
-  "Report at the milestones, not every step: what was found, what was done, what is next, in words for people; a problem as a problem, with what it blocks. What people read on the board, the reports, the questions and their options, the tasks and the pages, is written in {language}. The result goes in a last report or is handed in as a link or a file, with the check that ran and its result; a check that did not run is said to be not run.",
+  "Report at the milestones, not every step: what was found, what was done, what is next, in words for people; a problem as a problem, with what it blocks. What people read on the board, the reports, the questions and their options, the tasks and the pages, is written in {language}. A task's title says what is to be done, in plain words that stand on their own; what it refers to, a milestone, a commit, a page, goes in the body, linked where it can be. The result goes in a last report or is handed in as a link or a file, with the check that ran and its result; a check that did not run is said to be not run. A report is the run's record; a word to the task's people, an answer to what they asked in its comments, a question that is not a decision, a remark, is a comment on the task (`console comment`), and what they put in a comment is read with `console file`.",
   "",
   "## What never happens",
   "",

package/src/schemas.ts

@@ -647,8 +647,10 @@ export const restEventDataSchema = z.object({
   status: z.optional(z.enum(RUN_STATUSES)),
   /** For `run.handed_in`: what the artifact is called. */
   label: z.optional(z.string()),
-  /** For `run.reported`: the first words of the report. */
+  /** For `run.reported` and `task.commented`: the first words of what was written. */
   excerpt: z.optional(z.string()),
+  /** For `task.commented`: how many files came with it. */
+  files: z.optional(z.int()),
 });
 export type RestEventData = z.infer<typeof restEventDataSchema>;
 
@@ -740,6 +742,34 @@ export type RestRun = z.infer<typeof restRunSchema>;
 export const restRunsSchema = z.object({ items: z.array(restRunSchema), more: z.boolean() });
 export type RestRuns = z.infer<typeof restRunsSchema>;
 
+/** A file put in a comment, kept as a run's file is; its bytes are at `projectPath(key, "files", <id>)`. */
+export const restCommentFileSchema = z.object({
+  id: uuid,
+  file: restFileSchema,
+});
+export type RestCommentFile = z.infer<typeof restCommentFileSchema>;
+
+/**
+ * A word in the discussion on a task (ADR-0024): by a person, or by their agent, with the
+ * files put in it. Never rewritten: a mistake is corrected in the next one.
+ */
+export const restCommentSchema = z.object({
+  id: uuid,
+  taskId: uuid,
+  author: restPersonSchema,
+  /** The agent the author wrote through, or `null` when a person wrote it themselves. */
+  agent: z.nullable(z.string()),
+  /** Markdown. A picture among the files is placed in it as `![words](its name)`. */
+  body: z.string(),
+  files: z.array(restCommentFileSchema),
+  createdAt: instant,
+});
+export type RestComment = z.infer<typeof restCommentSchema>;
+
+/** `GET .../tasks/<id>/comments`: the discussion on a task, oldest first, whole. */
+export const restCommentsSchema = z.object({ items: z.array(restCommentSchema) });
+export type RestComments = z.infer<typeof restCommentsSchema>;
+
 /** `GET .../events?after=`: what happened after that number, oldest first. */
 export const restEventsSchema = z.object({
   items: z.array(restEventSchema),
@@ -1032,6 +1062,15 @@ export const restReportInputSchema = z.object({
 });
 export type RestReportInput = z.infer<typeof restReportInputSchema>;
 
+/**
+ * What `POST .../tasks/<id>/comments` is sent as JSON: the word, in Markdown. As a form, the
+ * part `body` says the same and the parts `file` carry the files; then the body may be blank.
+ */
+export const restCommentInputSchema = z.object({
+  body,
+});
+export type RestCommentInput = z.infer<typeof restCommentInputSchema>;
+
 /** What `POST .../runs/<id>/artifacts` is sent: a link to what was made. */
 export const restArtifactInputSchema = z.object({
   url,