@camox/api-contract 0.75.0 → 0.76.0

package/dist/threads.d.ts

@@ -69,6 +69,14 @@ export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
  * call of it went through ends on the draft's card.
  */
 export declare const START_DRAFT_TOOL = "startDraft";
+/**
+ * The agent on Live's tool restoring an archived draft and handing the editor to it, as
+ * `startDraft` does (ADR 0025, ADR 0046). A run whose call of it went through ends on the
+ * draft's card.
+ */
+export declare const RESTORE_DRAFT_TOOL = "restoreDraft";
+/** Whether a call of the tool `name` hands the editor off to a draft, which ends the run on its card. */
+export declare const handsOffToDraft: (name: string) => name is "restoreDraft" | "startDraft";
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 export declare const BUILD_TOOL = "build";
 /** The agent's tool rendering the draft in a browser and returning screenshots to the model. */
@@ -140,21 +148,27 @@ export declare const handsOff: (name: string) => boolean;
  * keeps this in step with the tools themselves.
  */
 export declare const CHANGING_TOOLS: ReadonlySet<string>;
-/** The draft a `startDraft` call started, as its result's details name it for the card. */
+/**
+ * The draft a `startDraft` call started, or a `restoreDraft` call restored, as its result's
+ * details name it for the card.
+ */
 export declare const startedDraftCardSchema: z.ZodObject<{
   draftId: z.ZodString;
   name: z.ZodString;
+  restored: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 export type StartedDraftCard = z.infer<typeof startedDraftCardSchema>;
 /**
  * Where a draft a Live thread's card names stands, as the thread looks it up whenever it's shown
- * (ADR 0025): its current name, or its last once it ended, and how it ended. Never written into
- * the transcript, so the model's cached prompt keeps up. A name cleared by a rename is null: the
- * card keeps the name the agent gave it.
+ * (ADR 0025): its current name, or its last once it ended, and how it ended. An archived draft
+ * hasn't ended: `archived` says it's set aside until someone restores it (ADR 0046). Never written
+ * into the transcript, so the model's cached prompt keeps up. A name cleared by a rename is null:
+ * the card keeps the name the agent gave it.
  */
 export type DraftCardState = {
   name: string | null;
   ended?: DraftOutcome;
+  archived?: true;
 };
 /** The drafts a Live thread's cards name, by id, as the thread last looked them up. */
 export type DraftCardStates = Readonly<Record<string, DraftCardState>>;
@@ -245,13 +259,14 @@ export declare const editorMessageDataSchema: z.ZodObject<{
   operationId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
- * A draft the agent on Live started with `startDraft`, and the operation ids of the messages of
- * the run that started it: the studio that sent one of them enters the draft, if it still shows
+ * A draft the agent on Live started with `startDraft`, or restored with `restoreDraft`, and the
+ * operation ids of the messages of the run that did: the studio that sent one of them enters the draft, if it still shows
  * Live.
  */
 export declare const startedDraftSchema: z.ZodObject<{
   draftId: z.ZodString;
   operationIds: z.ZodArray<z.ZodString>;
+  restored: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
 export type StartedDraft = z.infer<typeof startedDraftSchema>;
 /** How a write touched what it names. */
@@ -405,12 +420,14 @@ export type ThreadMessage = {
 /**
  * In place of the agent's message, for a Live turn handed off to a draft the agent started:
  * the draft's card, with its current name, which opens it. Once the draft ended, it has its
- * last name and how it ended, and opens nothing. The turn is finished.
+ * last name and how it ended, and opens nothing. While the draft is archived, `archived` is set,
+ * and the card offers to restore it. The turn is finished.
  */
 ({
   id: string;
   from: "draft";
   ended?: DraftOutcome;
+  archived?: true;
 } & StartedDraftCard) |
 /**
  * A member's push to the draft's code from their own checkout: who pushed, their commits'

package/dist/threads.js

@@ -66,6 +66,14 @@ const pushOutcomeSchema = z.enum([
 * call of it went through ends on the draft's card.
 */
 const START_DRAFT_TOOL = "startDraft";
+/**
+* The agent on Live's tool restoring an archived draft and handing the editor to it, as
+* `startDraft` does (ADR 0025, ADR 0046). A run whose call of it went through ends on the
+* draft's card.
+*/
+const RESTORE_DRAFT_TOOL = "restoreDraft";
+/** Whether a call of the tool `name` hands the editor off to a draft, which ends the run on its card. */
+const handsOffToDraft = (name) => name === "startDraft" || name === "restoreDraft";
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 const BUILD_TOOL = "build";
 /** The agent's tool rendering the draft in a browser and returning screenshots to the model. */
@@ -138,6 +146,7 @@ const CHANGING_TOOLS = /* @__PURE__ */ new Set([
 	"addBackToLocale",
 	"addLocale",
 	"applyFindingFix",
+	"copyFromPastWork",
 	"createBlock",
 	"createCollectionRecord",
 	"createPage",
@@ -158,10 +167,15 @@ const CHANGING_TOOLS = /* @__PURE__ */ new Set([
 	"rm",
 	"write"
 ]);
-/** The draft a `startDraft` call started, as its result's details name it for the card. */
+/**
+* The draft a `startDraft` call started, or a `restoreDraft` call restored, as its result's
+* details name it for the card.
+*/
 const startedDraftCardSchema = z.object({
 	draftId: z.string(),
-	name: z.string()
+	name: z.string(),
+	/** The agent restored the archived draft rather than starting it (ADR 0046). */
+	restored: z.literal(true).optional()
 });
 const reconcileDataSchema = z.object({ message: z.string() });
 const buildStatusSchema = z.enum(["building", "fixing"]);
@@ -210,13 +224,18 @@ const pushDataSchema = z.object({
 /** What an editor's message entry records: who sent it, and the operation id it was sent with. */
 const editorMessageDataSchema = threadSenderSchema.extend({ operationId: z.string().optional() });
 /**
-* A draft the agent on Live started with `startDraft`, and the operation ids of the messages of
-* the run that started it: the studio that sent one of them enters the draft, if it still shows
+* A draft the agent on Live started with `startDraft`, or restored with `restoreDraft`, and the
+* operation ids of the messages of the run that did: the studio that sent one of them enters the draft, if it still shows
 * Live.
 */
 const startedDraftSchema = z.object({
 	draftId: z.string(),
-	operationIds: z.array(z.string())
+	operationIds: z.array(z.string()),
+	/**
+	* The agent restored the archived draft rather than starting it: its thread goes on from its
+	* own messages, without the run's.
+	*/
+	restored: z.literal(true).optional()
 });
 /** How a write touched what it names. */
 const touchKindSchema = z.enum([
@@ -460,7 +479,7 @@ function threadStepOf(entry) {
 				text: details.answer
 			};
 		}
-		const card = message.toolName === "startDraft" && !message.isError ? startedDraftCardSchema.safeParse(message.details).data : void 0;
+		const card = handsOffToDraft(message.toolName) && !message.isError ? startedDraftCardSchema.safeParse(message.details).data : void 0;
 		return card ? {
 			id,
 			type: "draft",
@@ -583,7 +602,9 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ch
 						from: "draft",
 						draftId: step.draftId,
 						name: draft?.name ?? step.name,
-						...draft?.ended && { ended: draft.ended }
+						...step.restored && { restored: true },
+						...draft?.ended && { ended: draft.ended },
+						...draft?.archived && { archived: true }
 					});
 				}
 				endTurn();
@@ -640,7 +661,7 @@ function activityOf({ status, toolCalls, callingTools, changing, checking, hande
 	if (status === "fixing") return "fixing";
 	if (toolCalls.some((call) => handsOff(call.name))) return handedOffActivity ?? "changing";
 	if (checking) return "checking";
-	if (calling("startDraft")) return "startingDraft";
+	if (toolCalls.some((call) => handsOffToDraft(call.name))) return "startingDraft";
 	if (changing) return "changing";
 	if (callingTools || toolCalls.length > 0) return "exploring";
 	return "thinking";
@@ -772,4 +793,4 @@ function reduceThreadFrame(state, frame) {
 }
 
 //#endregion
-export { ARTIFACT_REQUEST_ENTRY, ARTIFACT_TOOL, ASK_TOOL, BRIEF_ENTRY, BUILD_STATUS_ENTRY, BUILD_TOOL, CHANGING_TOOLS, CODE_REQUEST_ENTRY, CODE_TOOL, CONNECTED_AGENT_MESSAGE_ENTRY, DRAFT_CARD_ENTRY, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, LOOK_TOOL, PUSH_ENTRY, QUESTIONS_ENTRY, RECONCILE_ENTRY, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, agentActivitySchema, artifactRequestDataSchema, buildStatusDataSchema, buildStatusSchema, codeRequestDataSchema, connectedAgentClientSchema, connectedAgentMessageDataSchema, editorMessageDataSchema, editorSelectionSchema, editorTextOf, editorWhereSchema, handOffDetailsSchema, handsOff, isSender, messageAttachmentSchema, pushDataSchema, pushOutcomeSchema, questionsDataSchema, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };
+export { ARTIFACT_REQUEST_ENTRY, ARTIFACT_TOOL, ASK_TOOL, BRIEF_ENTRY, BUILD_STATUS_ENTRY, BUILD_TOOL, CHANGING_TOOLS, CODE_REQUEST_ENTRY, CODE_TOOL, CONNECTED_AGENT_MESSAGE_ENTRY, DRAFT_CARD_ENTRY, DRAFT_ENDED_ENTRY, EDITOR_MESSAGE_ENTRY, EMPTY_THREAD_STATE, EMPTY_THREAD_VIEW, LOOK_TOOL, PUSH_ENTRY, QUESTIONS_ENTRY, RECONCILE_ENTRY, RESTORE_DRAFT_TOOL, RUN_STOPPED_ENTRY, START_DRAFT_TOOL, THREAD_ENDED_CLOSE_CODE, agentActivitySchema, artifactRequestDataSchema, buildStatusDataSchema, buildStatusSchema, codeRequestDataSchema, connectedAgentClientSchema, connectedAgentMessageDataSchema, editorMessageDataSchema, editorSelectionSchema, editorTextOf, editorWhereSchema, handOffDetailsSchema, handsOff, handsOffToDraft, isSender, messageAttachmentSchema, pushDataSchema, pushOutcomeSchema, questionsDataSchema, reconcileDataSchema, reduceThreadEvents, reduceThreadFrame, reduceThreadState, startedDraftCardSchema, startedDraftSchema, textOf, threadClientMessageSchema, threadSenderSchema, threadViewOf, touchKindSchema, touchSchema, touchedBatchSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "license": "MIT",
   "files": [
     "src",

package/src/drafts.ts

@@ -158,6 +158,22 @@ export type EndedDraft = {
   endedAt: number;
 };
 
+/**
+ * A draft set aside without ending it (ADR 0046): who archived it, a member or Camox, and when.
+ * It keeps its id, changes, thread and code until it's restored or deleted.
+ */
+export type ArchivedDraft = {
+  draftId: string;
+  archivedBy: { id: string; name: string };
+  archivedAt: number;
+};
+
+/**
+ * The oRPC error code a request naming an archived draft fails with: its `data` is an
+ * `ArchivedDraft`. Nothing reads or writes the draft until it's restored.
+ */
+export const DRAFT_ARCHIVED_ERROR_CODE = "DRAFT_ARCHIVED";
+
 /**
  * The oRPC error code a request naming an ended draft fails with. Its `data` is an `EndedDraft`,
  * so a page can render Live and say who published or deleted the draft.

package/src/query-keys.ts

@@ -1,4 +1,4 @@
-import type { EndedDraft } from "./drafts";
+import type { ArchivedDraft, EndedDraft } from "./drafts";
 
 /**
  * Use TypeScript to enforce 'camox' as the first query key to ensure they're all namespaced.
@@ -58,6 +58,14 @@ export const queryKeys = {
     list: ["camox", "drafts", "list"],
     // The draft a viewer is in, scoped to it like content.
     get: ["camox", "drafts", "get"],
+    // Archived drafts (ADR 0046): under `all`, so whatever changes the drafts list refreshes it.
+    archived: ["camox", "drafts", "archived"],
+  },
+  // Publications (ADR 0045): the same for every viewer, whatever they're in.
+  publications: {
+    all: ["camox", "publications"],
+    list: ["camox", "publications", "list"],
+    get: ["camox", "publications", "get"],
   },
   // The Specialists of a scope: their reports and pending work.
   specialists: {
@@ -100,6 +108,9 @@ export type InvalidationMessage = {
 /** A draft was published or deleted: its viewers go back to Live. */
 export type DraftEndedMessage = { type: "draftEnded" } & EndedDraft;
 
+/** A draft was archived: its viewers go back to Live (ADR 0046). */
+export type DraftArchivedMessage = { type: "draftArchived" } & ArchivedDraft;
+
 /** A draft with code has a new revision, built with Camox's `sdkVersion`. */
 export type RevisionAnnouncement = { draftId: string; revisionId: string; sdkVersion: string };
 
@@ -107,4 +118,8 @@ export type RevisionAnnouncement = { draftId: string; revisionId: string; sdkVer
 export type RevisionMessage = { type: "revision" } & RevisionAnnouncement;
 
 /** Everything the project room broadcasts. */
-export type ProjectRoomMessage = InvalidationMessage | DraftEndedMessage | RevisionMessage;
+export type ProjectRoomMessage =
+  | InvalidationMessage
+  | DraftEndedMessage
+  | DraftArchivedMessage
+  | RevisionMessage;

package/src/threads.ts

@@ -81,6 +81,17 @@ export type PushOutcome = z.infer<typeof pushOutcomeSchema>;
  */
 export const START_DRAFT_TOOL = "startDraft";
 
+/**
+ * The agent on Live's tool restoring an archived draft and handing the editor to it, as
+ * `startDraft` does (ADR 0025, ADR 0046). A run whose call of it went through ends on the
+ * draft's card.
+ */
+export const RESTORE_DRAFT_TOOL = "restoreDraft";
+
+/** Whether a call of the tool `name` hands the editor off to a draft, which ends the run on its card. */
+export const handsOffToDraft = (name: string) =>
+  name === START_DRAFT_TOOL || name === RESTORE_DRAFT_TOOL;
+
 /** The agent's tool building its code changes mid-turn, which the end of a turn also does. */
 export const BUILD_TOOL = "build";
 
@@ -169,6 +180,7 @@ export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
   "addBackToLocale",
   "addLocale",
   "applyFindingFix",
+  "copyFromPastWork",
   "createBlock",
   "createCollectionRecord",
   "createPage",
@@ -191,17 +203,26 @@ export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
   "write",
 ]);
 
-/** The draft a `startDraft` call started, as its result's details name it for the card. */
-export const startedDraftCardSchema = z.object({ draftId: z.string(), name: z.string() });
+/**
+ * The draft a `startDraft` call started, or a `restoreDraft` call restored, as its result's
+ * details name it for the card.
+ */
+export const startedDraftCardSchema = z.object({
+  draftId: z.string(),
+  name: z.string(),
+  /** The agent restored the archived draft rather than starting it (ADR 0046). */
+  restored: z.literal(true).optional(),
+});
 export type StartedDraftCard = z.infer<typeof startedDraftCardSchema>;
 
 /**
  * Where a draft a Live thread's card names stands, as the thread looks it up whenever it's shown
- * (ADR 0025): its current name, or its last once it ended, and how it ended. Never written into
- * the transcript, so the model's cached prompt keeps up. A name cleared by a rename is null: the
- * card keeps the name the agent gave it.
+ * (ADR 0025): its current name, or its last once it ended, and how it ended. An archived draft
+ * hasn't ended: `archived` says it's set aside until someone restores it (ADR 0046). Never written
+ * into the transcript, so the model's cached prompt keeps up. A name cleared by a rename is null:
+ * the card keeps the name the agent gave it.
  */
-export type DraftCardState = { name: string | null; ended?: DraftOutcome };
+export type DraftCardState = { name: string | null; ended?: DraftOutcome; archived?: true };
 
 /** The drafts a Live thread's cards name, by id, as the thread last looked them up. */
 export type DraftCardStates = Readonly<Record<string, DraftCardState>>;
@@ -269,13 +290,18 @@ export const editorMessageDataSchema = threadSenderSchema.extend({
 });
 
 /**
- * A draft the agent on Live started with `startDraft`, and the operation ids of the messages of
- * the run that started it: the studio that sent one of them enters the draft, if it still shows
+ * A draft the agent on Live started with `startDraft`, or restored with `restoreDraft`, and the
+ * operation ids of the messages of the run that did: the studio that sent one of them enters the draft, if it still shows
  * Live.
  */
 export const startedDraftSchema = z.object({
   draftId: z.string(),
   operationIds: z.array(z.string()),
+  /**
+   * The agent restored the archived draft rather than starting it: its thread goes on from its
+   * own messages, without the run's.
+   */
+  restored: z.literal(true).optional(),
 });
 export type StartedDraft = z.infer<typeof startedDraftSchema>;
 
@@ -359,9 +385,10 @@ export type ThreadMessage =
   /**
    * In place of the agent's message, for a Live turn handed off to a draft the agent started:
    * the draft's card, with its current name, which opens it. Once the draft ended, it has its
-   * last name and how it ended, and opens nothing. The turn is finished.
+   * last name and how it ended, and opens nothing. While the draft is archived, `archived` is set,
+   * and the card offers to restore it. The turn is finished.
    */
-  | ({ id: string; from: "draft"; ended?: DraftOutcome } & StartedDraftCard)
+  | ({ id: string; from: "draft"; ended?: DraftOutcome; archived?: true } & StartedDraftCard)
   /**
    * A member's push to the draft's code from their own checkout: who pushed, their commits'
    * subjects, oldest first, and how the pushed head built. It's no turn: the agent doesn't
@@ -659,7 +686,7 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
       if (details?.final && details.answer) return { id, type: "answer", text: details.answer };
     }
     const card =
-      message.toolName === START_DRAFT_TOOL && !message.isError
+      handsOffToDraft(message.toolName) && !message.isError
         ? startedDraftCardSchema.safeParse(message.details).data
         : undefined;
     return card ? { id, type: "draft", ...card } : { id, type: "tools" };
@@ -771,7 +798,9 @@ export function threadViewOf({
             from: "draft",
             draftId: step.draftId,
             name: draft?.name ?? step.name,
+            ...(step.restored && { restored: true as const }),
             ...(draft?.ended && { ended: draft.ended }),
+            ...(draft?.archived && { archived: true as const }),
           });
         }
         endTurn();
@@ -850,7 +879,7 @@ function activityOf({
   // the agent's.
   if (toolCalls.some((call) => handsOff(call.name))) return handedOffActivity ?? "changing";
   if (checking) return "checking";
-  if (calling(START_DRAFT_TOOL)) return "startingDraft";
+  if (toolCalls.some((call) => handsOffToDraft(call.name))) return "startingDraft";
   if (changing) return "changing";
   if (callingTools || toolCalls.length > 0) return "exploring";
   return "thinking";