feat: add protocol TIER-2 schemas (FactoryDroidMessage, SessionSource, MissionModelSettings) (#53)

Continue the protocol source-of-truth migration with the clean TIER-2
schemas — those needing only a small bundle of already-migrated leaf enums.

- messages.ts: add FactoryDroidMessageSchema + FactoryDroidMessageWithCaching
  (all content-block + enum deps landed in TIER-1)
- session-source.ts: SessionSourceSchema + platform sources (needs SessionPlatform)
- model-settings.ts: MissionModelSettingsSchema + SubagentModelSettingsSchema
  (symbol-only extraction; needs ReasoningEffort)

mission-decomposition is deferred: MissionFeatureSchema transitively pulls
CustomModelsSchema, which carries an apiKey credential field — not safe to
mirror publicly without trimming. Shapes mirror the private monorepo exactly.
Adds round-trip tests; src/protocol/ still not wired into the public API.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: varin-nair-factory

src/protocol/index.ts

@@ -1,13 +1,15 @@
-// Barrel for the new protocol source-of-truth modules.
+// Barrel for the protocol source-of-truth modules.
 // These files mirror the private factory-mono-alpha protocol exactly and are
 // intentionally self-contained (zod-only). NOT yet wired into the public
-// package API (src/index.ts) — this is the first migration step.
+// package API (src/index.ts).
 
 export * from './constants.js';
 export * from './enums.js';
 export * from './json-rpc.js';
 export * from './host.js';
 export * from './session.js';
+export * from './session-source.js';
 export * from './messages.js';
+export * from './model-settings.js';
 export * from './loop.js';
 export * from './selectable-list-item.js';

src/protocol/messages.ts

@@ -1,15 +1,18 @@
 // Source-of-truth mirror of factory-mono-alpha message content-block schemas.
-// Faithful copy of the content-block stack from
+// Faithful copy of the message schemas from
 //   packages/common/src/sessionV2/messages/schemas.ts
-// EXCLUDING FactoryDroidMessageSchema / FactoryDroidMessageWithCachingSchema,
-// which are deferred to a later (TIER-2) migration step.
 
 import { z } from 'zod';
 
 import {
+  ChatCompletionReasoningField,
   DocumentSourceType,
   MessageContentBlockType,
+  MessageRole,
+  MessageVisibility,
   ModelProvider,
+  OpenAIPhase,
+  SessionOrigin,
 } from './enums.js';
 
 // Base content block with optional id field
@@ -124,6 +127,44 @@ export const CacheLabelSchema = z.object({
     .optional(),
 });
 
+// FactoryDroidMessage schema (used in JSON-RPC protocol and application)
+export const FactoryDroidMessageSchema = z.object({
+  id: z.string(),
+  role: z.nativeEnum(MessageRole),
+  content: z.array(ContentBlockSchema),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  parentId: z.string().optional(),
+  userMessageSource: z.nativeEnum(SessionOrigin).optional(),
+  visibility: z.nativeEnum(MessageVisibility).optional(),
+  openaiMessageId: z.string().optional(),
+  openaiPhase: z
+    .enum([OpenAIPhase.Commentary, OpenAIPhase.FinalAnswer])
+    .nullable()
+    .optional(),
+  openaiEncryptedContent: z.string().optional(),
+  openaiReasoningId: z.string().optional(),
+  openaiReasoningSummary: z.string().optional(),
+  geminiThoughtSignature: z
+    .string()
+    .optional()
+    .describe(
+      '@deprecated Use thinking block `signature` fields with `signatureProvider: "google"` instead. Do not use in new code.'
+    ),
+  chatCompletionReasoningField: z
+    .nativeEnum(ChatCompletionReasoningField)
+    .optional(),
+  chatCompletionReasoningContent: z.string().optional(),
+  isUserVisible: z.boolean().optional(), // deprecated
+  isError: z.boolean().optional(),
+});
+
+// FactoryDroidMessageWithCaching schema
+export const FactoryDroidMessageWithCachingSchema =
+  FactoryDroidMessageSchema.extend({
+    content: z.array(ContentBlockSchema.and(CacheLabelSchema)),
+  });
+
 export type TextBlock = z.infer<typeof TextBlockSchema>;
 export type Base64ImageSource = z.infer<typeof Base64ImageSourceSchema>;
 export type ImageBlock = z.infer<typeof ImageBlockSchema>;
@@ -137,3 +178,7 @@ export type DocumentBlock = z.infer<typeof DocumentBlockSchema>;
 export type ToolResult = z.infer<typeof ToolResultSchema>;
 export type ContentBlock = z.infer<typeof ContentBlockSchema>;
 export type CacheLabel = z.infer<typeof CacheLabelSchema>;
+export type FactoryDroidMessage = z.infer<typeof FactoryDroidMessageSchema>;
+export type FactoryDroidMessageWithCaching = z.infer<
+  typeof FactoryDroidMessageWithCachingSchema
+>;

src/protocol/model-settings.ts

@@ -0,0 +1,31 @@
+// Source-of-truth mirror of factory-mono-alpha model-settings schemas (symbol-only).
+// Faithful copies of MissionModelSettingsSchema and SubagentModelSettingsSchema
+// from packages/common/src/settings/schema.ts. Only these leaf symbols are
+// mirrored here (not the full, TIER-3 settings file).
+
+import { z } from 'zod';
+
+import { ReasoningEffort } from './enums.js';
+
+const ReasoningEffortSchema = z.nativeEnum(ReasoningEffort);
+
+export const MissionModelSettingsSchema = z.object({
+  workerModel: z.string().optional(),
+  workerReasoningEffort: ReasoningEffortSchema.optional(),
+  validationWorkerModel: z.string().optional(),
+  validationWorkerReasoningEffort: ReasoningEffortSchema.optional(),
+  skipScrutiny: z.boolean().optional(),
+  skipUserTesting: z.boolean().optional(),
+});
+
+export const SubagentModelSettingsSchema = z.object({
+  lightModel: z.string().optional(),
+  lightReasoningEffort: ReasoningEffortSchema.optional(),
+  mediumModel: z.string().optional(),
+  mediumReasoningEffort: ReasoningEffortSchema.optional(),
+  heavyModel: z.string().optional(),
+  heavyReasoningEffort: ReasoningEffortSchema.optional(),
+});
+
+export type MissionModelSettings = z.infer<typeof MissionModelSettingsSchema>;
+export type SubagentModelSettings = z.infer<typeof SubagentModelSettingsSchema>;

src/protocol/session-source.ts

@@ -0,0 +1,136 @@
+// Source-of-truth mirror of factory-mono-alpha session source schemas.
+// Faithful copy of packages/common/src/session/sources/schema.ts.
+
+import { z } from 'zod';
+
+import { SessionPlatform } from './enums.js';
+
+// -------------------------------------------------------------
+// Platform source schemas (used for messages and sessions)
+// -------------------------------------------------------------
+
+const SlackSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.Slack),
+  teamId: z.string().nullish(),
+  channel: z.string().nullish(),
+  threadTs: z.string().nullish(),
+  userId: z.string().nullish(),
+});
+
+const WebSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.Web),
+});
+
+const ApiSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.Api),
+});
+
+const SessionsApiSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.SessionsApi),
+});
+
+const LinearSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.Linear),
+  agentSessionId: z.string(),
+  issueId: z.string().nullish(),
+  issueUrl: z.string().nullish(),
+  issueIdentifier: z.string().nullish(),
+  organizationId: z.string().nullish(),
+  userId: z.string().nullish(),
+});
+
+const ReadinessRemediationSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.ReadinessRemediation),
+  reportId: z.string(),
+  repoUrl: z.string(),
+  criterionId: z.string(),
+});
+
+const ReadinessEvaluationSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.ReadinessEvaluation),
+  repoUrl: z.string(),
+});
+
+const AutomationSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.Automation),
+  automationId: z.string(),
+  computerId: z.string(),
+});
+
+const WikiGenerationSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.WikiGeneration),
+  repoUrl: z.string(),
+});
+
+const WikiCISetupSourceSchema = z.object({
+  platform: z.literal(SessionPlatform.WikiCISetup),
+  repoUrl: z.string(),
+});
+
+// -------------------------------------------------------------
+// Session-specific source schemas (adds delegationSessionId)
+// -------------------------------------------------------------
+
+const SlackSessionSourceSchema = SlackSourceSchema.extend({
+  delegationSessionId: z.string(),
+});
+
+const WebSessionSourceSchema = WebSourceSchema.extend({
+  delegationSessionId: z.string(),
+});
+
+const ApiSessionSourceSchema = ApiSourceSchema.extend({
+  delegationSessionId: z.string(),
+});
+
+const SessionsApiSessionSourceSchema = SessionsApiSourceSchema.extend({
+  delegationSessionId: z.string(),
+});
+
+const LinearSessionSourceSchema = LinearSourceSchema.extend({
+  delegationSessionId: z.string(),
+});
+
+export const SessionSourceSchema = z.discriminatedUnion('platform', [
+  SlackSessionSourceSchema,
+  WebSessionSourceSchema,
+  ApiSessionSourceSchema,
+  SessionsApiSessionSourceSchema,
+  LinearSessionSourceSchema,
+  ReadinessRemediationSourceSchema, // No delegationSessionId needed
+  ReadinessEvaluationSourceSchema, // No delegationSessionId needed
+  AutomationSourceSchema, // No delegationSessionId needed
+  WikiGenerationSourceSchema, // No delegationSessionId needed
+  WikiCISetupSourceSchema, // No delegationSessionId needed
+]);
+
+// -------------------------------------------------------------
+// Inferred types (single source of truth)
+// -------------------------------------------------------------
+
+export type SlackSource = z.infer<typeof SlackSourceSchema>;
+export type WebSource = z.infer<typeof WebSourceSchema>;
+export type ApiSource = z.infer<typeof ApiSourceSchema>;
+export type SessionsApiSource = z.infer<typeof SessionsApiSourceSchema>;
+export type LinearSource = z.infer<typeof LinearSourceSchema>;
+export type ReadinessRemediationSource = z.infer<
+  typeof ReadinessRemediationSourceSchema
+>;
+export type ReadinessEvaluationSource = z.infer<
+  typeof ReadinessEvaluationSourceSchema
+>;
+export type AutomationSource = z.infer<typeof AutomationSourceSchema>;
+export type WikiGenerationSource = z.infer<typeof WikiGenerationSourceSchema>;
+export type WikiCISetupSource = z.infer<typeof WikiCISetupSourceSchema>;
+export type PlatformSource =
+  | SlackSource
+  | WebSource
+  | ApiSource
+  | SessionsApiSource
+  | LinearSource
+  | ReadinessRemediationSource
+  | ReadinessEvaluationSource
+  | AutomationSource
+  | WikiGenerationSource
+  | WikiCISetupSource;
+export type SessionSource = z.infer<typeof SessionSourceSchema>;

tests/protocol-dir.test.ts

@@ -10,6 +10,9 @@ import {
   JsonRpcErrorCode,
   JsonRpcMessageType,
   MessageContentBlockType,
+  MessageRole,
+  ReasoningEffort,
+  SessionPlatform,
 } from '../src/protocol/enums.js';
 import { HostIdSchema } from '../src/protocol/host.js';
 import {
@@ -18,7 +21,13 @@ import {
   JsonRpcMessageSchema,
 } from '../src/protocol/json-rpc.js';
 import { LoopStateSchema } from '../src/protocol/loop.js';
-import { ContentBlockSchema, ToolUseSchema } from '../src/protocol/messages.js';
+import {
+  ContentBlockSchema,
+  FactoryDroidMessageSchema,
+  ToolUseSchema,
+} from '../src/protocol/messages.js';
+import { MissionModelSettingsSchema } from '../src/protocol/model-settings.js';
+import { SessionSourceSchema } from '../src/protocol/session-source.js';
 import { SessionTagSchema, TokenUsageSchema } from '../src/protocol/session.js';
 
 const envelope = {
@@ -143,3 +152,45 @@ describe('protocol/host + session + loop', () => {
     ).toThrow();
   });
 });
+
+describe('protocol TIER-2', () => {
+  it('parses a FactoryDroidMessage with content blocks', () => {
+    const message = FactoryDroidMessageSchema.parse({
+      id: 'msg-1',
+      role: MessageRole.Assistant,
+      content: [{ type: MessageContentBlockType.Text, text: 'hello' }],
+      createdAt: 1,
+      updatedAt: 2,
+    });
+    expect(message.role).toBe(MessageRole.Assistant);
+    expect(message.content).toHaveLength(1);
+  });
+
+  it('rejects a FactoryDroidMessage missing required fields', () => {
+    expect(() =>
+      FactoryDroidMessageSchema.parse({ id: 'msg-1', role: MessageRole.User })
+    ).toThrow();
+  });
+
+  it('parses a discriminated SessionSource', () => {
+    const source = SessionSourceSchema.parse({
+      platform: SessionPlatform.Web,
+      delegationSessionId: 'deleg-1',
+    });
+    expect(source.platform).toBe(SessionPlatform.Web);
+  });
+
+  it('rejects a SessionSource with an unknown platform', () => {
+    expect(() => SessionSourceSchema.parse({ platform: 'nope' })).toThrow();
+  });
+
+  it('parses MissionModelSettings (all fields optional)', () => {
+    expect(MissionModelSettingsSchema.parse({})).toEqual({});
+    const settings = MissionModelSettingsSchema.parse({
+      workerModel: 'gpt-x',
+      workerReasoningEffort: ReasoningEffort.High,
+      skipScrutiny: true,
+    });
+    expect(settings.workerReasoningEffort).toBe(ReasoningEffort.High);
+  });
+});