@camox/api-contract 0.77.0 → 0.79.0

package/dist/threads.d.ts

@@ -44,6 +44,11 @@ export declare const BRIEF_ENTRY = "camox.brief";
  * it at the end of the conversation; editors never see it, since the draft's card says so.
  */
 export declare const DRAFT_ENDED_ENTRY = "camox.draft-ended";
+/**
+ * The kind of the transcript entry holding Camox's note on memory, as it read when it changed
+ * since the model last saw it (ADR 0049). Only the model reads it.
+ */
+export declare const MEMORY_ENTRY = "camox.memory";
 /**
  * The kind of the transcript entry a Live thread starts afresh from once its agent handed a
  * request off to a draft (ADR 0036): a reset of Pi's context, with a `startedDraftCardSchema` as

package/dist/threads.js

@@ -43,6 +43,11 @@ const BRIEF_ENTRY = "camox.brief";
 */
 const DRAFT_ENDED_ENTRY = "camox.draft-ended";
 /**
+* The kind of the transcript entry holding Camox's note on memory, as it read when it changed
+* since the model last saw it (ADR 0049). Only the model reads it.
+*/
+const MEMORY_ENTRY = "camox.memory";
+/**
 * The kind of the transcript entry a Live thread starts afresh from once its agent handed a
 * request off to a draft (ADR 0036): a reset of Pi's context, with a `startedDraftCardSchema` as
 * data. Editors see an empty thread, and the model reads a note naming the draft. Everything
@@ -145,18 +150,23 @@ const handsOff = (name) => HANDING_OFF_TOOLS.has(name);
 const CHANGING_TOOLS = /* @__PURE__ */ new Set([
 	"addBackToLocale",
 	"addLocale",
+	"addMemory",
 	"applyFindingFix",
+	"changeMemory",
+	"changeVoice",
 	"copyFromPastWork",
 	"createBlock",
 	"createCollectionRecord",
 	"createPage",
 	"deleteBlock",
 	"deleteCollectionRecord",
+	"deleteMemory",
 	"deletePage",
 	"editBlock",
 	"editCollectionRecord",
 	"moveBlock",
 	"removeLocale",
+	"retranslateLocale",
 	"retranslateLocalization",
 	"setPageLayout",
 	"setPageSeo",
@@ -425,7 +435,7 @@ function threadStepOf(entry) {
 			status: build.status
 		};
 	}
-	if (entry.kind === "camox.draft-ended") return void 0;
+	if (entry.kind === "camox.draft-ended" || entry.kind === "camox.memory") return void 0;
 	if (entry.kind === "camox.push") {
 		const push = pushDataSchema.safeParse(entry.data).data;
 		return push && {
@@ -801,4 +811,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, 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 };
+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, MEMORY_ENTRY, 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/dist/voice.d.ts

@@ -0,0 +1,191 @@
+//#region src/voice.d.ts
+/**
+ * The Voice Axes, each with its steps in order and each step's one-line definition. The Voice is
+ * a limit, not a target, and each axis's `limit` says how: under a `ceiling`, copy may sit at any
+ * step below the chosen one, never above; in a `band`, within one step of it either way.
+ */
+export declare const VOICE_AXES: readonly [{
+  readonly key: "formality";
+  readonly limit: "band";
+  readonly name: "Formality";
+  readonly about: "register, grammar, vocabulary";
+  readonly steps: readonly [{
+    readonly key: "ceremonial";
+    readonly name: "Ceremonial";
+    readonly definition: "elevated, ritual register; no contractions; set phrases and honorifics.";
+  }, {
+    readonly key: "formal";
+    readonly name: "Formal";
+    readonly definition: "correct and impersonal; no contractions or slang; complete sentences.";
+  }, {
+    readonly key: "neutral";
+    readonly name: "Neutral";
+    readonly definition: "standard written register; contractions allowed; no slang.";
+  }, {
+    readonly key: "conversational";
+    readonly name: "Conversational";
+    readonly definition: "as spoken to a customer; contractions, short sentences, questions to the reader.";
+  }, {
+    readonly key: "colloquial";
+    readonly name: "Colloquial";
+    readonly definition: "as spoken among friends; slang, fragments, loose grammar.";
+  }];
+}, {
+  readonly key: "humor";
+  readonly limit: "ceiling";
+  readonly name: "Humor";
+  readonly about: null;
+  readonly steps: readonly [{
+    readonly key: "grave";
+    readonly name: "Grave";
+    readonly definition: "solemn and weighty; treats its subject with gravity, beyond having no jokes.";
+  }, {
+    readonly key: "earnest";
+    readonly name: "Earnest";
+    readonly definition: "sincere and straightforward; no jokes.";
+  }, {
+    readonly key: "light";
+    readonly name: "Light";
+    readonly definition: "warm, with an occasional light touch; no set-up jokes.";
+  }, {
+    readonly key: "witty";
+    readonly name: "Witty";
+    readonly definition: "jokes, irony or playful exaggeration recur.";
+  }, {
+    readonly key: "irreverent";
+    readonly name: "Irreverent";
+    readonly definition: "mocks conventions, the industry or itself; jokes over sincerity.";
+  }];
+}, {
+  readonly key: "claimStrength";
+  readonly limit: "ceiling";
+  readonly name: "Claim strength";
+  readonly about: "how strongly copy praises and promises, backed or not; calls to action count only when they push urgency";
+  readonly steps: readonly [{
+    readonly key: "understated";
+    readonly name: "Understated";
+    readonly definition: "states facts only; no praise words; qualifies claims.";
+  }, {
+    readonly key: "measured";
+    readonly name: "Measured";
+    readonly definition: "modest claims; praise words are rare.";
+  }, {
+    readonly key: "confident";
+    readonly name: "Confident";
+    readonly definition: "states benefits plainly; few praise words, no superlatives.";
+  }, {
+    readonly key: "assertive";
+    readonly name: "Assertive";
+    readonly definition: "praise words throughout; strong claims and comparisons.";
+  }, {
+    readonly key: "bold";
+    readonly name: "Bold";
+    readonly definition: "superlatives, sweeping promises, urgency, exclamations.";
+  }];
+}, {
+  readonly key: "expertise";
+  readonly limit: "ceiling";
+  readonly name: "Expertise";
+  readonly about: "what the reader is assumed to know";
+  readonly steps: readonly [{
+    readonly key: "plain";
+    readonly name: "Plain";
+    readonly definition: "everyday words only; no terms of the trade.";
+  }, {
+    readonly key: "accessible";
+    readonly name: "Accessible";
+    readonly definition: "terms of the trade only when explained.";
+  }, {
+    readonly key: "informed";
+    readonly name: "Informed";
+    readonly definition: "common terms of the trade, unexplained.";
+  }, {
+    readonly key: "technical";
+    readonly name: "Technical";
+    readonly definition: "precise terms, specifications and figures for practitioners.";
+  }, {
+    readonly key: "specialist";
+    readonly name: "Specialist";
+    readonly definition: "dense jargon and references only experts follow.";
+  }];
+}, {
+  readonly key: "density";
+  readonly limit: "ceiling";
+  readonly name: "Density";
+  readonly about: "words per idea, not page length";
+  readonly steps: readonly [{
+    readonly key: "telegraphic";
+    readonly name: "Telegraphic";
+    readonly definition: "fragments and lists; articles and transitions dropped where possible.";
+  }, {
+    readonly key: "concise";
+    readonly name: "Concise";
+    readonly definition: "one idea per short sentence; nothing restated.";
+  }, {
+    readonly key: "balanced";
+    readonly name: "Balanced";
+    readonly definition: "each idea gets the sentence it needs, with transitions.";
+  }, {
+    readonly key: "descriptive";
+    readonly name: "Descriptive";
+    readonly definition: "ideas get detail, qualification and imagery.";
+  }, {
+    readonly key: "expansive";
+    readonly name: "Expansive";
+    readonly definition: "ideas developed at length, with asides and restatement.";
+  }];
+}, {
+  readonly key: "distance";
+  readonly limit: "band";
+  readonly name: "Distance";
+  readonly about: "who speaks, how close";
+  readonly steps: readonly [{
+    readonly key: "institutional";
+    readonly name: "Institutional";
+    readonly definition: "the organization speaks of itself by name, in the third person, and doesn't address the reader.";
+  }, {
+    readonly key: "collective";
+    readonly name: "Collective";
+    readonly definition: '"we" speak about readers in general.';
+  }, {
+    readonly key: "direct";
+    readonly name: "Direct";
+    readonly definition: '"we" speak to "you".';
+  }, {
+    readonly key: "personal";
+    readonly name: "Personal";
+    readonly definition: '"we" speak to "you" one to one, sharing opinions and feelings.';
+  }, {
+    readonly key: "solo";
+    readonly name: "Solo";
+    readonly definition: 'one person speaks as "I".';
+  }];
+}];
+/** One Voice Axis, with its steps in order. */
+export type VoiceAxis = (typeof VOICE_AXES)[number];
+export type VoiceAxisKey = VoiceAxis["key"];
+/** A step of the axis `A`. */
+export type VoiceStep<A extends VoiceAxisKey = VoiceAxisKey> = Extract<VoiceAxis, {
+  key: A;
+}>["steps"][number];
+/** The key of a step of the axis `A`. */
+export type VoiceStepKey<A extends VoiceAxisKey = VoiceAxisKey> = VoiceStep<A>["key"];
+/** A Voice: the chosen step on each axis. */
+export type Voice = { [A in VoiceAxisKey]: VoiceStepKey<A>; };
+/** The Voice a new project starts with: no hype, no wordiness, no forced jokes. */
+export declare const DEFAULT_VOICE: Voice;
+/** The axis with this key. */
+export declare const voiceAxis: <A extends VoiceAxisKey>(key: A) => Extract<VoiceAxis, {
+  key: A;
+}>;
+/** Whether `key` names a step of the axis `axis`. */
+export declare const isVoiceStep: <A extends VoiceAxisKey>(axis: A, key: string) => key is VoiceStepKey<A>;
+/** The step with this key on the axis `axis`. */
+export declare const voiceStep: <A extends VoiceAxisKey>(axis: A, key: VoiceStepKey<A>) => VoiceStep<A>;
+/** An axis a draft moves: from Live's step to the draft's. */
+export type VoiceChange = { [A in VoiceAxisKey]: {
+  axis: A;
+  before: VoiceStepKey<A>;
+  after: VoiceStepKey<A>;
+}; }[VoiceAxisKey];
+//#endregion

package/dist/voice.js

@@ -0,0 +1,228 @@
+//#region src/voice.ts
+/**
+* The Voice Axes, each with its steps in order and each step's one-line definition. The Voice is
+* a limit, not a target, and each axis's `limit` says how: under a `ceiling`, copy may sit at any
+* step below the chosen one, never above; in a `band`, within one step of it either way.
+*/
+const VOICE_AXES = [
+	{
+		key: "formality",
+		limit: "band",
+		name: "Formality",
+		about: "register, grammar, vocabulary",
+		steps: [
+			{
+				key: "ceremonial",
+				name: "Ceremonial",
+				definition: "elevated, ritual register; no contractions; set phrases and honorifics."
+			},
+			{
+				key: "formal",
+				name: "Formal",
+				definition: "correct and impersonal; no contractions or slang; complete sentences."
+			},
+			{
+				key: "neutral",
+				name: "Neutral",
+				definition: "standard written register; contractions allowed; no slang."
+			},
+			{
+				key: "conversational",
+				name: "Conversational",
+				definition: "as spoken to a customer; contractions, short sentences, questions to the reader."
+			},
+			{
+				key: "colloquial",
+				name: "Colloquial",
+				definition: "as spoken among friends; slang, fragments, loose grammar."
+			}
+		]
+	},
+	{
+		key: "humor",
+		limit: "ceiling",
+		name: "Humor",
+		about: null,
+		steps: [
+			{
+				key: "grave",
+				name: "Grave",
+				definition: "solemn and weighty; treats its subject with gravity, beyond having no jokes."
+			},
+			{
+				key: "earnest",
+				name: "Earnest",
+				definition: "sincere and straightforward; no jokes."
+			},
+			{
+				key: "light",
+				name: "Light",
+				definition: "warm, with an occasional light touch; no set-up jokes."
+			},
+			{
+				key: "witty",
+				name: "Witty",
+				definition: "jokes, irony or playful exaggeration recur."
+			},
+			{
+				key: "irreverent",
+				name: "Irreverent",
+				definition: "mocks conventions, the industry or itself; jokes over sincerity."
+			}
+		]
+	},
+	{
+		key: "claimStrength",
+		limit: "ceiling",
+		name: "Claim strength",
+		about: "how strongly copy praises and promises, backed or not; calls to action count only when they push urgency",
+		steps: [
+			{
+				key: "understated",
+				name: "Understated",
+				definition: "states facts only; no praise words; qualifies claims."
+			},
+			{
+				key: "measured",
+				name: "Measured",
+				definition: "modest claims; praise words are rare."
+			},
+			{
+				key: "confident",
+				name: "Confident",
+				definition: "states benefits plainly; few praise words, no superlatives."
+			},
+			{
+				key: "assertive",
+				name: "Assertive",
+				definition: "praise words throughout; strong claims and comparisons."
+			},
+			{
+				key: "bold",
+				name: "Bold",
+				definition: "superlatives, sweeping promises, urgency, exclamations."
+			}
+		]
+	},
+	{
+		key: "expertise",
+		limit: "ceiling",
+		name: "Expertise",
+		about: "what the reader is assumed to know",
+		steps: [
+			{
+				key: "plain",
+				name: "Plain",
+				definition: "everyday words only; no terms of the trade."
+			},
+			{
+				key: "accessible",
+				name: "Accessible",
+				definition: "terms of the trade only when explained."
+			},
+			{
+				key: "informed",
+				name: "Informed",
+				definition: "common terms of the trade, unexplained."
+			},
+			{
+				key: "technical",
+				name: "Technical",
+				definition: "precise terms, specifications and figures for practitioners."
+			},
+			{
+				key: "specialist",
+				name: "Specialist",
+				definition: "dense jargon and references only experts follow."
+			}
+		]
+	},
+	{
+		key: "density",
+		limit: "ceiling",
+		name: "Density",
+		about: "words per idea, not page length",
+		steps: [
+			{
+				key: "telegraphic",
+				name: "Telegraphic",
+				definition: "fragments and lists; articles and transitions dropped where possible."
+			},
+			{
+				key: "concise",
+				name: "Concise",
+				definition: "one idea per short sentence; nothing restated."
+			},
+			{
+				key: "balanced",
+				name: "Balanced",
+				definition: "each idea gets the sentence it needs, with transitions."
+			},
+			{
+				key: "descriptive",
+				name: "Descriptive",
+				definition: "ideas get detail, qualification and imagery."
+			},
+			{
+				key: "expansive",
+				name: "Expansive",
+				definition: "ideas developed at length, with asides and restatement."
+			}
+		]
+	},
+	{
+		key: "distance",
+		limit: "band",
+		name: "Distance",
+		about: "who speaks, how close",
+		steps: [
+			{
+				key: "institutional",
+				name: "Institutional",
+				definition: "the organization speaks of itself by name, in the third person, and doesn't address the reader."
+			},
+			{
+				key: "collective",
+				name: "Collective",
+				definition: "\"we\" speak about readers in general."
+			},
+			{
+				key: "direct",
+				name: "Direct",
+				definition: "\"we\" speak to \"you\"."
+			},
+			{
+				key: "personal",
+				name: "Personal",
+				definition: "\"we\" speak to \"you\" one to one, sharing opinions and feelings."
+			},
+			{
+				key: "solo",
+				name: "Solo",
+				definition: "one person speaks as \"I\"."
+			}
+		]
+	}
+];
+/** The Voice a new project starts with: no hype, no wordiness, no forced jokes. */
+const DEFAULT_VOICE = {
+	formality: "conversational",
+	humor: "earnest",
+	claimStrength: "confident",
+	expertise: "accessible",
+	density: "concise",
+	distance: "direct"
+};
+/** The axis with this key. */
+const voiceAxis = (key) => VOICE_AXES.find((axis) => axis.key === key);
+/** Whether `key` names a step of the axis `axis`. */
+const isVoiceStep = (axis, key) => {
+	return voiceAxis(axis).steps.some((step) => step.key === key);
+};
+/** The step with this key on the axis `axis`. */
+const voiceStep = (axis, key) => {
+	return voiceAxis(axis).steps.find((step) => step.key === key);
+};
+
+//#endregion
+export { DEFAULT_VOICE, VOICE_AXES, isVoiceStep, voiceAxis, voiceStep };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.77.0",
-  "license": "MIT",
+  "version": "0.79.0",
+  "license": "UNLICENSED",
   "files": [
     "src",
     "dist"
@@ -59,6 +59,10 @@
     "./claim-links": {
       "types": "./dist/claim-links.d.ts",
       "default": "./dist/claim-links.js"
+    },
+    "./voice": {
+      "types": "./dist/voice.d.ts",
+      "default": "./dist/voice.js"
     }
   },
   "dependencies": {

package/src/drafts.ts

@@ -335,12 +335,23 @@ const SPECIALISTS_WRITES: Record<keyof Router["specialists"], boolean> = {
   dismissFinding: false,
 };
 
+// Memory, the Voice included, changes through drafts, like content (ADR 0049, ADR 0051).
+const MEMORY_WRITES: Record<keyof Router["memories"], boolean> = {
+  list: false,
+  add: true,
+  change: true,
+  delete: true,
+  voice: false,
+  saveVoice: true,
+};
+
 // `definitions` is absent: its sync is a release, never a studio content write.
 const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
   blocks: BLOCK_WRITES,
   locales: LOCALE_WRITES,
   collectionDefinitions: COLLECTION_WRITES,
   files: FILE_WRITES,
+  memories: MEMORY_WRITES,
   pages: PAGE_WRITES,
   specialists: SPECIALISTS_WRITES,
   // The old name of `specialists`, for studios not yet upgraded (ADR 0019).

package/src/query-keys.ts

@@ -52,6 +52,11 @@ export const queryKeys = {
   layouts: {
     all: ["camox", "layouts"],
   },
+  // A scope's memory (ADR 0049), and its Voice (ADR 0051).
+  memories: {
+    list: ["camox", "memories", "list"],
+    voice: ["camox", "memories", "voice"],
+  },
   drafts: {
     all: ["camox", "drafts"],
     // Open drafts and Live's latest publish: the same for every viewer, whatever they're in.

package/src/threads.ts

@@ -56,6 +56,12 @@ export const BRIEF_ENTRY = "camox.brief";
  */
 export const DRAFT_ENDED_ENTRY = "camox.draft-ended";
 
+/**
+ * The kind of the transcript entry holding Camox's note on memory, as it read when it changed
+ * since the model last saw it (ADR 0049). Only the model reads it.
+ */
+export const MEMORY_ENTRY = "camox.memory";
+
 /**
  * The kind of the transcript entry a Live thread starts afresh from once its agent handed a
  * request off to a draft (ADR 0036): a reset of Pi's context, with a `startedDraftCardSchema` as
@@ -179,18 +185,23 @@ export const CHANGING_TOOLS: ReadonlySet<string> = new Set([
   // Content
   "addBackToLocale",
   "addLocale",
+  "addMemory",
   "applyFindingFix",
+  "changeMemory",
+  "changeVoice",
   "copyFromPastWork",
   "createBlock",
   "createCollectionRecord",
   "createPage",
   "deleteBlock",
   "deleteCollectionRecord",
+  "deleteMemory",
   "deletePage",
   "editBlock",
   "editCollectionRecord",
   "moveBlock",
   "removeLocale",
+  "retranslateLocale",
   "retranslateLocalization",
   "setPageLayout",
   "setPageSeo",
@@ -643,7 +654,7 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
     return build && { id, type: "build", status: build.status };
   }
   // Only the model reads it: as a user message, it would otherwise read as Pi continuing a run.
-  if (entry.kind === DRAFT_ENDED_ENTRY) return undefined;
+  if (entry.kind === DRAFT_ENDED_ENTRY || entry.kind === MEMORY_ENTRY) return undefined;
   if (entry.kind === PUSH_ENTRY) {
     const push = pushDataSchema.safeParse(entry.data).data;
     return push && { id, type: "push", ...push };