@futurity/chat-protocol 0.0.1

package/src/chat-websocket.ts

@@ -0,0 +1,219 @@
+// Canonical wire format for chat WebSocket messages (client ↔ server).
+// Browser-safe — no Node.js imports.
+import { z } from "zod";
+import { Z_MessagePart } from "./message-parts";
+
+// ── Supporting schemas ───────────────────────────────────
+
+export const wsMessageMetadataSchema = z.object({
+  parent_id: z.string().uuid().nullable(),
+});
+
+export const wsMessageSchema = z.object({
+  id: z.string(),
+  role: z.enum(["user", "assistant", "system"]),
+  parts: z.array(Z_MessagePart),
+  metadata: wsMessageMetadataSchema.optional(),
+});
+
+export const wsVaultItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  url: z.string(),
+});
+
+export const wsClarifyOptionSchema = z.object({
+  label: z.string(),
+  description: z.string(),
+});
+
+export const wsClarifyQuestionSchema = z.object({
+  question: z.string(),
+  header: z.string(),
+  options: z.array(wsClarifyOptionSchema),
+  multiSelect: z.boolean(),
+});
+
+// ── Client → Server commands ─────────────────────────────
+
+export const wsRunCommandSchema = z.object({
+  type: z.literal("run"),
+  data: z.object({
+    id: z.string(),
+    message: wsMessageSchema,
+    vaultItems: z.array(wsVaultItemSchema),
+    timezone: z.string(),
+  }),
+});
+
+export const wsGetChatCommandSchema = z.object({
+  type: z.literal("get_chat"),
+  data: z.object({
+    chat_id: z.string(),
+  }),
+});
+
+export const wsCancelCommandSchema = z.object({
+  type: z.literal("cancel"),
+  data: z.object({
+    job_id: z.string(),
+  }),
+});
+
+export const wsClarifyResponseCommandSchema = z.object({
+  type: z.literal("clarify_response"),
+  data: z.object({
+    job_id: z.string(),
+    requestId: z.string(),
+    answers: z.record(z.string(), z.string()),
+  }),
+});
+
+export const wsInjectMessageCommandSchema = z.object({
+  type: z.literal("inject_message"),
+  data: z.object({
+    job_id: z.string(),
+    text: z.string().max(50000),
+    message_id: z.string().uuid(),
+  }),
+});
+
+export const wsClientCommandSchema = z.discriminatedUnion("type", [
+  wsRunCommandSchema,
+  wsGetChatCommandSchema,
+  wsCancelCommandSchema,
+  wsClarifyResponseCommandSchema,
+  wsInjectMessageCommandSchema,
+]);
+
+// ── Server → Client messages ─────────────────────────────
+
+export const wsReadyMessageSchema = z.object({
+  type: z.literal("ready"),
+  data: z.object({
+    success: z.boolean(),
+  }),
+});
+
+export const wsRunMessageSchema = z.object({
+  type: z.literal("run"),
+  data: z.object({
+    job_id: z.string(),
+    message_id: z.string(),
+  }),
+});
+
+export const wsStreamMessageSchema = z.object({
+  type: z.literal("stream"),
+  jobId: z.string(),
+  chatId: z.string(),
+  messageId: z.string(),
+  delta: Z_MessagePart,
+  index: z.number(),
+  consolidated: z.boolean().optional().default(false),
+  partsLength: z.number(),
+});
+
+export const wsStreamResumeMessageSchema = z.object({
+  type: z.literal("stream_resume"),
+  jobId: z.string(),
+  chatId: z.string(),
+  messageId: z.string(),
+  parts: z.array(Z_MessagePart),
+});
+
+export const wsErrorMessageSchema = z.object({
+  type: z.literal("error"),
+  error: z.string().optional(),
+  message: z.string().optional(),
+  data: z.any().optional(),
+});
+
+export const wsChatHistoryMessageSchema = z.object({
+  type: z.literal("chat_history"),
+  data: z.object({
+    messages: z.array(z.any()),
+    activeMessageId: z.string().optional(),
+  }),
+});
+
+export const wsCancelMessageSchema = z.object({
+  type: z.literal("cancel"),
+  data: z.object({
+    job_id: z.string(),
+    success: z.boolean(),
+    reason: z.string().optional(),
+  }),
+});
+
+export const wsDoneMessageSchema = z.object({
+  type: z.literal("done"),
+  data: z.object({
+    job_id: z.string(),
+  }),
+});
+
+export const wsClarifyRequestMessageSchema = z.object({
+  type: z.literal("clarify_request"),
+  data: z.object({
+    job_id: z.string(),
+    requestId: z.string(),
+    questions: z.array(wsClarifyQuestionSchema),
+  }),
+});
+
+export const wsInjectAckMessageSchema = z.object({
+  type: z.literal("inject_ack"),
+  data: z.object({
+    job_id: z.string(),
+    inject_message_id: z.string(),
+    new_assistant_id: z.string(),
+  }),
+});
+
+export const wsInjectSplitMessageSchema = z.object({
+  type: z.literal("inject_split"),
+  data: z.object({
+    job_id: z.string(),
+    new_message_id: z.string(),
+  }),
+});
+
+export const wsServerMessageSchema = z.discriminatedUnion("type", [
+  wsReadyMessageSchema,
+  wsRunMessageSchema,
+  wsStreamMessageSchema,
+  wsStreamResumeMessageSchema,
+  wsErrorMessageSchema,
+  wsChatHistoryMessageSchema,
+  wsCancelMessageSchema,
+  wsDoneMessageSchema,
+  wsClarifyRequestMessageSchema,
+  wsInjectAckMessageSchema,
+  wsInjectSplitMessageSchema,
+]);
+
+// ── Inferred types ───────────────────────────────────────
+
+export type WsClientCommand = z.infer<typeof wsClientCommandSchema>;
+export type WsServerMessage = z.infer<typeof wsServerMessageSchema>;
+
+export type WsReadyMessage = z.infer<typeof wsReadyMessageSchema>;
+export type WsRunMessage = z.infer<typeof wsRunMessageSchema>;
+export type WsStreamMessage = z.infer<typeof wsStreamMessageSchema>;
+export type WsStreamResumeMessage = z.infer<typeof wsStreamResumeMessageSchema>;
+export type WsErrorMessage = z.infer<typeof wsErrorMessageSchema>;
+export type WsChatHistoryMessage = z.infer<typeof wsChatHistoryMessageSchema>;
+export type WsCancelMessage = z.infer<typeof wsCancelMessageSchema>;
+export type WsDoneMessage = z.infer<typeof wsDoneMessageSchema>;
+export type WsClarifyRequestMessage = z.infer<
+  typeof wsClarifyRequestMessageSchema
+>;
+export type WsClarifyQuestion = z.infer<typeof wsClarifyQuestionSchema>;
+export type WsClarifyOption = z.infer<typeof wsClarifyOptionSchema>;
+export type WsInjectAckMessage = z.infer<typeof wsInjectAckMessageSchema>;
+export type WsInjectSplitMessage = z.infer<typeof wsInjectSplitMessageSchema>;
+
+export type WsVaultItem = z.infer<typeof wsVaultItemSchema>;
+export type WsMessage = z.infer<typeof wsMessageSchema>;
+export type WsMessageMetadata = z.infer<typeof wsMessageMetadataSchema>;

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./chat-websocket";
+export * from "./message-parts";

package/src/message-parts.ts

@@ -0,0 +1,326 @@
+// Canonical Z_MessagePart union used across the monorepo.
+// Browser-safe — no Node.js imports. Keep in sync with packages/db/src/schema/ai.schema.ts.
+import { z } from "zod";
+
+export const Z_ProviderMetadataSchema = z.record(
+  z.string(),
+  z.record(z.string(), z.any()),
+);
+
+export const Z_TextUIPartSchema = z.object({
+  type: z.literal("text"),
+  text: z.string(),
+  state: z.enum(["streaming", "done"]).optional(),
+  providerMetadata: Z_ProviderMetadataSchema.optional(),
+});
+
+export const Z_ReasoningUIPartSchema = z.object({
+  type: z.literal("reasoning"),
+  text: z.string(),
+  state: z.enum(["streaming", "done"]).optional(),
+  providerMetadata: Z_ProviderMetadataSchema.optional(),
+});
+
+export const Z_SourceUrlUIPartSchema = z.object({
+  type: z.literal("source-url"),
+  sourceId: z.string(),
+  url: z.string(),
+  title: z.string().optional(),
+  providerMetadata: Z_ProviderMetadataSchema.optional(),
+});
+
+export const Z_SourceDocumentUIPartSchema = z.object({
+  type: z.literal("source-document"),
+  sourceId: z.string(),
+  mediaType: z.string(),
+  title: z.string(),
+  filename: z.string().optional(),
+  providerMetadata: Z_ProviderMetadataSchema.optional(),
+});
+
+export const Z_FileUIPartSchema = z.object({
+  type: z.literal("file"),
+  mediaType: z.string(),
+  filename: z.string().optional(),
+  url: z.string(),
+  providerMetadata: Z_ProviderMetadataSchema.optional(),
+});
+
+export const Z_StepStartUIPartSchema = z.object({
+  type: z.literal("step-start"),
+});
+
+// Data UI Part (generic data with dynamic type names)
+export const Z_DataUIPartSchema = z.object({
+  type: z.custom<`data-${string}`>((value) => {
+    return typeof value === "string" && value.startsWith("data-");
+  }),
+  id: z.string().optional(),
+  data: z.unknown(),
+});
+
+// Specific data part schemas for subagent UI markers
+export const Z_DataSplitSchema = z.object({
+  type: z.literal("data-split"),
+  data: z.object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    desktopSessionId: z.string().optional(),
+    subAgentId: z.string().optional(),
+  }),
+});
+
+export const Z_DataEndSplitSchema = z.object({
+  type: z.literal("data-endsplit"),
+  data: z
+    .object({
+      desktopSessionId: z.string().optional(),
+      subAgentId: z.string().optional(),
+    })
+    .optional(),
+});
+
+export const Z_DataSubagentPartSchema = z.object({
+  type: z.literal("data-subagent-part"),
+  data: z.object({
+    subAgentId: z.string(),
+    part: z.unknown(),
+  }),
+});
+
+export const Z_DataStatusSchema = z.object({
+  type: z.literal("data-status"),
+  id: z.string().optional(),
+  data: z.object({
+    status: z.enum(["loading", "ready", "error"]),
+    text: z.string(),
+  }),
+});
+
+export const Z_DataClarifyResponseSchema = z.object({
+  type: z.literal("data-clarify-response"),
+  data: z.object({
+    answers: z.record(z.string(), z.string()),
+  }),
+});
+
+export const Z_DataScreenshotSchema = z.object({
+  type: z.literal("data-screenshot"),
+  data: z.object({
+    src: z.string(),
+    toolName: z.string().optional(),
+  }),
+});
+
+export const Z_DataViewSwitchSchema = z.object({
+  type: z.literal("data-view-switch"),
+  data: z.object({
+    view: z.enum(["browser", "terminal"]),
+  }),
+});
+
+export const Z_DataFileHighlightSchema = z.object({
+  type: z.literal("data-file-highlight"),
+  data: z.object({
+    path: z.string(),
+    label: z.string().optional(),
+  }),
+});
+
+// Tool Invocation schemas
+export const Z_BaseToolInvocationSchema = z.object({
+  toolCallId: z.string(),
+  title: z.string().optional(),
+  providerExecuted: z.boolean().optional(),
+});
+
+export const Z_ToolInvocationInputStreamingSchema =
+  Z_BaseToolInvocationSchema.extend({
+    state: z.literal("input-streaming"),
+    input: z.unknown(),
+    callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+  });
+
+export const Z_ToolInvocationInputAvailableSchema =
+  Z_BaseToolInvocationSchema.extend({
+    state: z.literal("input-available"),
+    input: z.unknown(),
+    callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+  });
+
+export const Z_ToolInvocationApprovalRequestedSchema =
+  Z_BaseToolInvocationSchema.extend({
+    state: z.literal("approval-requested"),
+    input: z.unknown(),
+    callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+    approval: z.object({
+      id: z.string(),
+    }),
+  });
+
+export const Z_ToolInvocationApprovalRespondedSchema =
+  Z_BaseToolInvocationSchema.extend({
+    state: z.literal("approval-responded"),
+    input: z.unknown(),
+    callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+    approval: z.object({
+      id: z.string(),
+      approved: z.boolean(),
+      reason: z.string().optional(),
+    }),
+  });
+
+export const Z_ToolInvocationOutputAvailableSchema =
+  Z_BaseToolInvocationSchema.extend({
+    state: z.literal("output-available"),
+    input: z.unknown(),
+    output: z.unknown(),
+    callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+    preliminary: z.boolean().optional(),
+    approval: z
+      .object({
+        id: z.string(),
+        approved: z.literal(true),
+        reason: z.string().optional(),
+      })
+      .optional(),
+  });
+
+export const Z_ToolInvocationOutputErrorSchema =
+  Z_BaseToolInvocationSchema.extend({
+    state: z.literal("output-error"),
+    input: z.unknown(),
+    rawInput: z.unknown().optional(),
+    errorText: z.string(),
+    callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+    approval: z
+      .object({
+        id: z.string(),
+        approved: z.literal(true),
+        reason: z.string().optional(),
+      })
+      .optional(),
+  });
+
+export const Z_ToolInvocationOutputDeniedSchema =
+  Z_BaseToolInvocationSchema.extend({
+    state: z.literal("output-denied"),
+    input: z.unknown(),
+    callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+    approval: z.object({
+      id: z.string(),
+      approved: z.literal(false),
+      reason: z.string().optional(),
+    }),
+  });
+
+export const Z_ToolInvocationSchema = z.discriminatedUnion("state", [
+  Z_ToolInvocationInputStreamingSchema,
+  Z_ToolInvocationInputAvailableSchema,
+  Z_ToolInvocationApprovalRequestedSchema,
+  Z_ToolInvocationApprovalRespondedSchema,
+  Z_ToolInvocationOutputAvailableSchema,
+  Z_ToolInvocationOutputErrorSchema,
+  Z_ToolInvocationOutputDeniedSchema,
+]);
+
+// Tool UI Part (static tool with specific name)
+export const Z_ToolUIPartSchema = z
+  .object({
+    type: z.custom<`tool-${string}`>((value) => {
+      return typeof value === "string" && value.startsWith("tool-");
+    }),
+  })
+  .and(Z_ToolInvocationSchema);
+
+export const Z_DynamicToolUIPartSchema = z
+  .object({
+    type: z.literal("dynamic-tool"),
+    toolName: z.string(),
+    toolCallId: z.string(),
+    title: z.string().optional(),
+    providerExecuted: z.boolean().optional(),
+  })
+  .and(
+    z.discriminatedUnion("state", [
+      z.object({
+        state: z.literal("input-streaming"),
+        input: z.unknown(),
+        callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+      }),
+      z.object({
+        state: z.literal("input-available"),
+        input: z.unknown(),
+        callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+      }),
+      z.object({
+        state: z.literal("approval-requested"),
+        input: z.unknown(),
+        callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+        approval: z.object({
+          id: z.string(),
+        }),
+      }),
+      z.object({
+        state: z.literal("approval-responded"),
+        input: z.unknown(),
+        callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+        approval: z.object({
+          id: z.string(),
+          approved: z.boolean(),
+          reason: z.string().optional(),
+        }),
+      }),
+      z.object({
+        state: z.literal("output-available"),
+        input: z.unknown(),
+        output: z.unknown(),
+        callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+        preliminary: z.boolean().optional(),
+        approval: z
+          .object({
+            id: z.string(),
+            approved: z.literal(true),
+            reason: z.string().optional(),
+          })
+          .optional(),
+      }),
+      z.object({
+        state: z.literal("output-error"),
+        input: z.unknown(),
+        errorText: z.string(),
+        callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+        approval: z
+          .object({
+            id: z.string(),
+            approved: z.literal(true),
+            reason: z.string().optional(),
+          })
+          .optional(),
+      }),
+      z.object({
+        state: z.literal("output-denied"),
+        input: z.unknown(),
+        callProviderMetadata: Z_ProviderMetadataSchema.optional(),
+        approval: z.object({
+          id: z.string(),
+          approved: z.literal(false),
+          reason: z.string().optional(),
+        }),
+      }),
+    ]),
+  );
+
+export const Z_MessagePart = z.union([
+  Z_TextUIPartSchema,
+  Z_ReasoningUIPartSchema,
+  Z_SourceUrlUIPartSchema,
+  Z_SourceDocumentUIPartSchema,
+  Z_FileUIPartSchema,
+  Z_StepStartUIPartSchema,
+  Z_DataUIPartSchema,
+  Z_ToolUIPartSchema,
+  Z_DynamicToolUIPartSchema,
+]);
+
+export type MessagePart = z.infer<typeof Z_MessagePart>;