@camox/api-contract 0.74.1 → 0.75.0

package/dist/router.d.ts

@@ -4,6 +4,9 @@ import { AgentActivity, ConnectedAgentClient, ThreadSender, ThreadView } from "@
 import { PiHarness, PiHarnessOptions } from "agents/harness/pi";
 import { CapabilityStartContext, Lifecycle } from "agents/lifecycle";
 import { WebSockets } from "agents/websockets";
+import "@earendil-works/pi-ai";
+import "@earendil-works/pi-ai/models";
+import "@earendil-works/pi-durable/tools";
 import { FileErrorCode } from "@earendil-works/pi-durable/env";
 import "camox/_internal/sdkBundleName";
 import "@camox/ai-tools";
@@ -38,6 +41,198 @@ declare class EdgeCachePurger extends DurableObject<Bindings> {
 //#region ../../apps/api/src/lib/edge-cache-purges.d.ts
 type EdgeCachePurgerNamespace = DurableObjectNamespace<EdgeCachePurger>;
 //#endregion
+//#region ../../apps/api/src/domains/attachments/schema.d.ts
+/**
+ * An Attachment (ADR 0044): an image a member's Connected Agent uploaded for Camox's agent to
+ * see with one of its messages. Its bytes are a blob in the files bucket, under their own
+ * `attachments/` key space, and its row is apart from files', so it never shows among the
+ * project's Files. It becomes a File only when the agent puts it on the website.
+ *
+ * An Attachment no message used yet lasts a day from `createdAt`. A used one lasts as long as any
+ * thread whose message used it (`attachmentUses`).
+ */
+declare const attachments: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+  name: "attachments";
+  schema: undefined;
+  columns: {
+    id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "id";
+      tableName: "attachments";
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: undefined;
+    }>;
+    projectId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "project_id";
+      tableName: "attachments";
+      dataType: "number";
+      columnType: "SQLiteInteger";
+      data: number;
+      driverParam: number;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    memberId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "member_id";
+      tableName: "attachments";
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: number | undefined;
+    }>;
+    filename: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "filename";
+      tableName: "attachments";
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: undefined;
+    }>;
+    mimeType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "mime_type";
+      tableName: "attachments";
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: "image/jpeg" | "image/png" | "image/svg+xml" | "image/webp";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: number | undefined;
+      $type: "image/jpeg" | "image/png" | "image/svg+xml" | "image/webp";
+    }>;
+    size: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "size";
+      tableName: "attachments";
+      dataType: "number";
+      columnType: "SQLiteInteger";
+      data: number;
+      driverParam: number;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    blobKey: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "blob_key";
+      tableName: "attachments";
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: number | undefined;
+    }>;
+    url: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "url";
+      tableName: "attachments";
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: string;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: undefined;
+    }>;
+    createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "created_at";
+      tableName: "attachments";
+      dataType: "number";
+      columnType: "SQLiteInteger";
+      data: number;
+      driverParam: number;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  };
+  dialect: 'sqlite';
+}>;
+type Attachment = typeof attachments.$inferSelect;
+//#endregion
+//#region ../../apps/api/src/domains/attachments/model-input.d.ts
+/**
+ * An Attachment as a thread message carries it: what a model's label and the studio name it by,
+ * and where its bytes are.
+ */
+type MessageAttachment = Pick<Attachment, "id" | "filename" | "mimeType" | "url" | "blobKey">;
+//#endregion
 //#region ../../apps/api/src/domains/code/remote-env.d.ts
 /** The operations sent as they are: every argument but the context is plain data. */
 declare const SENT: ["absolutePath", "joinPath", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "appendFile", "truncateFile", "flushFile", "renameFile", "fileInfo", "listDir", "canonicalPath", "exists", "createDir", "remove"];
@@ -9543,13 +9738,15 @@ type OpeningSender = {
 };
 /**
  * A message a draft's thread opens with: its text, the operation id it was sent with, and who
- * sent it. A Connected Agent's message may be its answer to the agent's questions (ADR 0042).
+ * sent it. A Connected Agent's message may be its answer to the agent's questions (ADR 0042), and
+ * may carry Attachments, images the model sees with it (ADR 0044).
  */
 type OpeningMessage = {
   operationId: string;
   text: string;
   from: OpeningSender;
   answer?: boolean;
+  attachments?: MessageAttachment[];
 };
 /**
  * How the API opens a draft's thread with no studio connected (`Thread.open`): what it belongs

package/dist/threads.d.ts

@@ -1,7 +1,7 @@
 import { DraftOutcome } from "./drafts.js";
 import { z } from "zod";
-import { AgentEvent } from "@earendil-works/pi-durable";
 import { Message } from "@earendil-works/pi-ai";
+import { AgentEvent } from "@earendil-works/pi-durable";
 //#region src/threads.d.ts
 /**
  * The kind of the transcript entry recording an editor's message, with its sender and the
@@ -190,6 +190,14 @@ export declare const connectedAgentClientSchema: z.ZodObject<{
   verified: z.ZodBoolean;
 }, z.core.$strip>;
 export type ConnectedAgentClient = z.infer<typeof connectedAgentClientSchema>;
+/** An Attachment a Connected Agent's message carries: an image the agent sees with it. */
+export declare const messageAttachmentSchema: z.ZodObject<{
+  id: z.ZodString;
+  filename: z.ZodString;
+  mimeType: z.ZodString;
+  url: z.ZodString;
+}, z.core.$strip>;
+export type MessageAttachmentData = z.infer<typeof messageAttachmentSchema>;
 /**
  * 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).
@@ -206,6 +214,12 @@ export declare const connectedAgentMessageDataSchema: z.ZodObject<{
   }, z.core.$strip>;
   operationId: z.ZodOptional<z.ZodString>;
   answer: z.ZodOptional<z.ZodBoolean>;
+  attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    filename: z.ZodString;
+    mimeType: z.ZodString;
+    url: z.ZodString;
+  }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ConnectedAgentMessageData = z.infer<typeof connectedAgentMessageDataSchema>;
 /** What a push's entry records: who pushed, their commits' subjects, oldest first, and the build. */
@@ -350,6 +364,8 @@ export type ThreadMessage = {
   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. */
 {
@@ -502,6 +518,7 @@ type ThreadStep = {
   client: ConnectedAgentClient;
   text: string;
   answer: boolean;
+  attachments?: MessageAttachmentData[];
 } |
 /** Camox starting a turn of its own, saying why. */
 {

package/dist/threads.js

@@ -182,6 +182,13 @@ const connectedAgentClientSchema = z.object({
 	name: z.string(),
 	verified: z.boolean()
 });
+/** An Attachment a Connected Agent's message carries: an image the agent sees with it. */
+const messageAttachmentSchema = z.object({
+	id: z.string(),
+	filename: z.string(),
+	mimeType: z.string(),
+	url: z.string()
+});
 /**
 * 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).
@@ -190,7 +197,9 @@ const connectedAgentMessageDataSchema = z.object({
 	member: threadSenderSchema,
 	client: connectedAgentClientSchema,
 	operationId: z.string().optional(),
-	answer: z.boolean().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()
 });
 /** What a push's entry records: who pushed, their commits' subjects, oldest first, and the build. */
 const pushDataSchema = z.object({
@@ -419,7 +428,8 @@ function threadStepOf(entry) {
 					verified: data.client.verified
 				},
 				text: editorTextOf(message.content),
-				answer: data.answer ?? false
+				answer: data.answer ?? false,
+				...data.attachments?.length && { attachments: data.attachments }
 			};
 		}
 		if (entry.kind === "camox.brief") return {
@@ -525,7 +535,8 @@ function threadViewOf({ steps, running, toolCalls = [], callingTools = false, ch
 					member: step.member,
 					client: step.client,
 					text: step.text,
-					answer: step.answer
+					answer: step.answer,
+					...step.attachments && { attachments: step.attachments }
 				});
 				waiting = step.id;
 				break;
@@ -761,4 +772,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, 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, 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 };

package/package.json

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

package/src/threads.ts

@@ -232,6 +232,15 @@ 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, the
  * operation id it was sent with, and whether it answers the agent's questions (ADR 0042).
@@ -241,6 +250,8 @@ export const connectedAgentMessageDataSchema = z.object({
   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>;
 
@@ -326,6 +337,8 @@ export type ThreadMessage =
       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 }
@@ -441,6 +454,7 @@ type ThreadStep = { id: string } & (
       client: ConnectedAgentClient;
       text: string;
       answer: boolean;
+      attachments?: MessageAttachmentData[];
     }
   /** Camox starting a turn of its own, saying why. */
   | { type: "camox"; text: string }
@@ -618,6 +632,7 @@ function threadStepOf(entry: EntryRecord): ThreadStep | undefined {
           client: { name: data.client.name, verified: data.client.verified },
           text: editorTextOf(message.content),
           answer: data.answer ?? false,
+          ...(data.attachments?.length && { attachments: data.attachments }),
         }
       );
     }
@@ -722,6 +737,7 @@ export function threadViewOf({
           client: step.client,
           text: step.text,
           answer: step.answer,
+          ...(step.attachments && { attachments: step.attachments }),
         });
         waiting = step.id;
         break;