chore(protocol): scrub internal references from public schemas

varin-nair-factory · factory-droid[bot] · varin-nair-factory · commit 0f4fa528682e · 2026-06-02T14:36:17.000-07:00
Strips internal-architecture references from src/protocol/** so they
no longer leak into the published bundles and source-maps:

- Remove file headers referencing the internal monorepo and verbatim
  port provenance from ~30 protocol files; replace with neutral
  one-line descriptions where useful.
- Scrub billing/architecture JSDoc on WorkerFailureReason and
  MissionPauseReason (the enum members are unchanged; only the
  descriptive comments around them are tightened).
- Drop the editorial 'Deprecated' / 'Extra Usage (overage) billing
  tier' comments from LLMModelTier members.
- Drop incidental references to internal infra (Vercel, Firestore
  sync, EAP cleanup, backend-v0-sessions, replay bug #974,
  MissionRunner / MissionFileService class names) from JSDoc and
  inline comments.
- Add *.tgz to .gitignore so packed builds aren't accidentally
  committed.

No schema, enum value, or exported symbol shape changes; bundle
parity against mono is unaffected (still 265/265 MATCH).

Co-authored-by: factory-droid[bot] &lt;138933559+factory-droid[bot]@users.noreply.github.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,7 @@ node_modules/
 
 # Build output
 dist/
+*.tgz
 
 # Coverage
 coverage/
diff --git a/src/protocol/cli.ts b/src/protocol/cli.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha CLI protocol schemas.
-// Verbatim copy of packages/common/src/droid/schemas/cli.ts.
-
 import { z } from 'zod';
 
 import { SandboxModeSchema } from './custom-models.js';
diff --git a/src/protocol/client.ts b/src/protocol/client.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha client protocol schemas.
-// Verbatim copy of packages/common/src/droid/schemas/client.ts.
-
 import { z } from 'zod';
 
 import {
diff --git a/src/protocol/constants.ts b/src/protocol/constants.ts
@@ -1,9 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha protocol constants.
-// Faithful copy of:
-//   packages/common/src/droid/schemas/constants.ts
-//   packages/common/src/droid/constants.ts (LOOP_INTERVAL_POLICY + system markers)
-// Keep shapes/values identical to the private monorepo to avoid protocol drift.
-
 import { DroidWorkingState } from './enums.js';
 
 export const FACTORY_CLIENT_HEADER = 'X-Factory-Client';
@@ -22,21 +16,16 @@ export const FACTORY_PROTOCOL_VERSION = '1.66.0' as const;
 export const JSONRPC_VERSION = '2.0' as const;
 
 /**
- * Sentinel ModelID value for the Factory routing model. Faithful copy of
- * packages/common/src/llm/constants.ts.
+ * Sentinel ModelID value for the Factory routing model. 
  */
 export const FACTORY_ROUTER_MODEL_ID = 'factory-router' as const;
 
 /**
  * Sentinel value used by CompactionModelSchema to mean "use the session's
- * current model for compaction". Faithful copy of
- * packages/common/src/settings/constants.ts.
+ * current model for compaction". 
  */
 export const CURRENT_COMPACTION_MODEL = 'current-model';
 
-// Faithful copy of packages/common/src/settings/constants.ts router-rule
-// guardrails. Used by ManagedSettingsBaseSchema and FactoryRouterRuleSchema.
-
 /** Sized comparably to a trimmed user message in the classifier context budget. */
 export const FACTORY_ROUTER_GUIDANCE_MAX_LENGTH = 2000;
 export const FACTORY_ROUTER_RULES_MAX_COUNT = 20;
diff --git a/src/protocol/crons.ts b/src/protocol/crons.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha droid crons tool-input schemas.
-// Verbatim copy of packages/common/src/droid/schemas/crons.ts.
-
 import { z } from 'zod';
 
 const CronExpressionSchema = z
diff --git a/src/protocol/custom-models.ts b/src/protocol/custom-models.ts
@@ -1,8 +1,5 @@
-// Source-of-truth mirror of factory-mono-alpha custom-model schemas (symbol-only).
-// Verbatim copy of CustomModelBedrockSchema, ManagedCustomModelSchema, and
-// CustomModelsSchema from packages/common/src/settings/schema.ts. Ported as-is
-// per the no-modification rule (includes apiKey / aws credential fields).
-// SandboxModeSchema is colocated here (one-liner from the same settings module).
+// Custom-model schemas (includes apiKey / aws credential fields).
+// SandboxModeSchema is colocated here.
 
 import { z } from 'zod';
 
diff --git a/src/protocol/daemon/automations.ts b/src/protocol/daemon/automations.ts
@@ -16,9 +16,9 @@ export const DaemonListAutomationsRequestSchema =
   });
 
 export const AutomationEntrySchema = z.object({
-  /** Directory name slug (e.g. "health-check"). Kept as `id` because protocol rules forbid renaming required fields. */
+  /** Directory name slug (e.g. "health-check"). */
   id: z.string(),
-  /** Stable UUID from HEARTBEAT.md frontmatter, used for backend/Firestore sync. */
+  /** Stable UUID for backend sync. */
   uuid: z.string().optional(),
   name: z.string(),
   description: z.string().optional(),
diff --git a/src/protocol/daemon/commands.ts b/src/protocol/daemon/commands.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha daemon commands schema.
-// Verbatim copy of packages/common/src/daemon/schemas/commands.ts.
-
 import { z } from 'zod';
 
 import { CustomCommandInfoSchema } from '../client.js';
diff --git a/src/protocol/daemon/connection.ts b/src/protocol/daemon/connection.ts
@@ -39,7 +39,7 @@ export const DaemonAuthenticateRequestParamsSchema = z
     apiKey: z.string().optional(),
     /** Frontend-generated connection ID for trace correlation */
     connectionId: z.string().optional(),
-    /** Caller identifier for debugging (e.g., 'frontend', 'backend-v0-sessions', 'cli') */
+    /** Caller identifier for debugging (e.g., 'frontend', 'cli'). */
     caller: z.string(),
     /** Client-supplied metadata for tracing and diagnostics. */
     metadata: DaemonConnectionMetadataSchema.optional(),
diff --git a/src/protocol/daemon/crons.ts b/src/protocol/daemon/crons.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha daemon crons schemas.
-// Verbatim copy of packages/common/src/daemon/schemas/crons.ts.
-
 import { z } from 'zod';
 
 import {
diff --git a/src/protocol/daemon/index.ts b/src/protocol/daemon/index.ts
@@ -1,5 +1,4 @@
 // Internal barrel for the daemon protocol source-of-truth modules.
-// Mirrors files under factory-mono-alpha/packages/common/src/daemon/schemas/.
 // NOT yet wired into the public package API (src/index.ts).
 
 export * from './enums.js';
diff --git a/src/protocol/enums.ts b/src/protocol/enums.ts
@@ -1,16 +1,4 @@
-// Source-of-truth mirror of factory-mono-alpha protocol enums (leaf enums only).
-// Faithful copies of the private monorepo definitions from:
-//   packages/common/src/shared/enums.ts
-//   packages/common/src/droid/enums.ts
-//   packages/common/src/sessionV2/messages/enums.ts
-//   packages/common/src/session/sources/enums.ts
-//   packages/common/src/llm/enums.ts (leaf subset)
-//   packages/common/src/settings/enums.ts (leaf subset)
-// Keep values byte-identical to the private monorepo to avoid protocol drift.
-
-// ---------------------------------------------------------------------------
-// shared/enums.ts
-// ---------------------------------------------------------------------------
+// Protocol enums (shared, droid, session, llm, settings, sources).
 
 export enum JsonRpcMessageType {
   Request = 'request',
@@ -407,28 +395,13 @@ export enum ProgressLogEntryType {
   MilestoneValidationTriggered = 'milestone_validation_triggered',
 }
 
-/**
- * Discriminator on `WorkerFailedEntry.failureReason` so the MissionRunner can
- * distinguish failure modes that should auto-pause the mission (e.g. an
- * unrecoverable 402) from generic worker exits that should be requeued and
- * retried by the orchestrator.
- */
+/** Structured failure cause used by orchestrators to branch on auto-pause vs requeue. */
 export enum WorkerFailureReason {
-  /**
-   * Worker LLM call returned 402 (Payment Required) and the in-process
-   * Droid Core fallback path was ineligible (overage preference != droidCore,
-   * already on Core, or no swap-eligible slot). The mission must auto-pause.
-   */
   UnrecoverableUsage402 = 'unrecoverable_usage_402',
 }
 
-/**
- * Discriminator on `MissionPausedEntry.pauseReason`. Default (`undefined`)
- * means a user- or runner-initiated pause; structured values mark
- * automatically-triggered pauses so the UI/orchestrator can react.
- */
+/** Structured cause for automatically-triggered mission pauses. */
 export enum MissionPauseReason {
-  /** Worker hit an unrecoverable 402 — usage limit reached. */
   UnrecoverableUsage402 = 'unrecoverable_usage_402',
 }
 
@@ -653,11 +626,11 @@ export enum ModelProvider {
 }
 
 export enum ApiProvider {
-  BEDROCK = 'bedrock', // Ideally we deprecate!
+  BEDROCK = 'bedrock',
   ANTHROPIC = 'anthropic',
-  VERTEX_ANTHROPIC = 'vertex_anthropic', // A minimal wrapper for Anthropic's API on GCP
-  BEDROCK_ANTHROPIC = 'bedrock_anthropic', // A minimal wrapper for Anthropic's API on AWS
-  BEDROCK_CONVERSE = 'bedrock_converse', // BYOK custom models over the Bedrock Converse API (metric labeling only)
+  VERTEX_ANTHROPIC = 'vertex_anthropic',
+  BEDROCK_ANTHROPIC = 'bedrock_anthropic',
+  BEDROCK_CONVERSE = 'bedrock_converse',
   OPENAI = 'openai',
   AZURE_OPENAI = 'azure_openai',
   GOOGLE = 'google',
@@ -674,9 +647,7 @@ export enum ModelKind {
 
 export enum LLMModelTier {
   Standard = 'standard',
-  // Deprecated
   Premium = 'premium',
-  // Extra Usage (overage) billing tier
   Overage = 'overage',
 }
 
diff --git a/src/protocol/general-settings.ts b/src/protocol/general-settings.ts
@@ -1,32 +1,3 @@
-// Source-of-truth mirror of `ManagedSettingsBaseSchema` and
-// `GeneralSettingsSchema` from `packages/common/src/settings/schema.ts`.
-// Verbatim port; do not modify the schema bodies. The only allowed
-// divergences are:
-//   1. Import paths are rewritten to local `./` siblings with `.js` ESM
-//      extensions (and helpers that already exist in sibling SDK modules
-//      are imported instead of redeclared).
-//   2. `ManagedSettingsBaseSchema` is `export const` here (upstream declares
-//      it `const`); the visibility is raised so `GeneralSettingsSchema` can
-//      call `.extend(...)` on it from a separate module boundary if needed
-//      and so the public API can surface it. See the inline NOTE below.
-//
-// Symbols ported verbatim (in upstream order):
-//   - SESSION_RETENTION_MIN_DAYS / SESSION_RETENTION_MAX_DAYS
-//   - ModelPolicySchema (+ private tolerantModelIdArray helper — upstream
-//     intentionally redefines this locally; we mirror that)
-//   - McpPolicySchema
-//   - MissionPolicySchema
-//   - NetworkPolicySchema (private, like upstream)
-//   - SandboxFilesystemSettingsSchema
-//   - SandboxNetworkSettingsSchema
-//   - SandboxSettingsSchema
-//   - ExtraMarketplaceEntrySchema (private, like upstream)
-//   - FactoryRouterRuleSchema
-//   - McpAutonomyLevelSchema (private, like upstream)
-//   - StatusLineConfigSchema (private, like upstream)
-//   - ManagedSettingsBaseSchema (exported; see NOTE)
-//   - GeneralSettingsSchema
-
 import { z } from 'zod';
 
 import {
@@ -67,10 +38,9 @@ const ReasoningEffortSchema = z.nativeEnum(ReasoningEffort);
 
 /**
  * A lenient model ID array that silently drops unrecognized values instead of
- * failing validation. This is critical for backward compatibility: when a ModelID
- * enum value is removed (e.g. after an EAP model cleanup), any Firestore
- * documents still referencing the old ID will have it filtered out rather than
- * causing the entire settings object to fail parsing.
+ * failing validation. Ensures backward compatibility when ModelID enum values
+ * are removed — persisted settings referencing old IDs filter them out rather
+ * than failing to parse.
  */
 const modelIdValues: ReadonlySet<string> = new Set(Object.values(ModelID));
 const tolerantModelIdArray = z
@@ -183,8 +153,8 @@ const StatusLineConfigSchema = z.object({
   maxRows: z.number().int().min(1).max(3).optional(),
 });
 
-// NOTE: upstream declares this `const`; exported here to allow `.extend(...)`
-// across module boundaries and to surface it on the public protocol namespace.
+// Exported (not internal-only) to allow `.extend(...)` across module
+// boundaries and to surface it on the public protocol namespace.
 export const ManagedSettingsBaseSchema = z.object({
   sessionDefaultSettings: SessionDefaultSettingsSchema.optional(),
   maxAutonomyLevel: z.nativeEnum(AutonomyLevel).optional(),
diff --git a/src/protocol/host.ts b/src/protocol/host.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha host schemas.
-// Faithful copy of packages/common/src/host/schemas.ts.
-
 import { z } from 'zod';
 
 export const HostIdSchema = z.string().uuid();
diff --git a/src/protocol/index.ts b/src/protocol/index.ts
@@ -1,7 +1,4 @@
 // 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).
 
 export * from './constants.js';
 export * from './enums.js';
@@ -35,10 +32,9 @@ export * from './tools.js';
 export * from './updater.js';
 
 // `./usage.js` defines its own `TokenUsageSchema` whose shape (snake-cased
-// integer fields) differs from the one in `./session.js`. Both upstream
-// modules ship the same symbol name (`TokenUsageSchema`) under different
-// folder namespaces, so we mirror that here by re-exporting `./usage.js`
-// under a namespace alias rather than as a top-level wildcard.
+// integer fields) differs from the one in `./session.js`. To keep both
+// symbols distinct on the public barrel, `./usage.js` is re-exported under a
+// namespace alias rather than as a top-level wildcard.
 export * as usage from './usage.js';
 
 export * as daemon from './daemon/index.js';
diff --git a/src/protocol/json-rpc.ts b/src/protocol/json-rpc.ts
@@ -1,8 +1,6 @@
-// Source-of-truth mirror of factory-mono-alpha JSON-RPC envelope family.
-// Faithful copy of packages/common/src/shared/schemas.ts.
-// Shapes match the private monorepo exactly (note: params/result/data use
-// z.unknown() as in the private source, NOT typed JsonValue). Do not "improve"
-// these shapes here — divergence from the private monorepo reintroduces drift.
+// JSON-RPC envelope/base protocol schemas.
+// Note: params/result/data use z.unknown() intentionally so envelopes carry
+// arbitrary payloads without typing the inner shape at this layer.
 
 import { z } from 'zod';
 
diff --git a/src/protocol/loop.ts b/src/protocol/loop.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha loop schemas.
-// Verbatim copy of packages/common/src/droid/schemas/loop.ts.
-
 import { z } from 'zod';
 
 import { DroidLoopStatus, DroidLoopStopReason } from './enums.js';
diff --git a/src/protocol/mcp.ts b/src/protocol/mcp.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha MCP schemas.
-// Verbatim copy of packages/common/src/droid/schemas/mcp.ts.
-
 import { z } from 'zod';
 
 import { McpServerStatus, McpServerType, SettingsLevel } from './enums.js';
diff --git a/src/protocol/messages.ts b/src/protocol/messages.ts
@@ -1,7 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha message content-block schemas.
-// Faithful copy of the message schemas from
-//   packages/common/src/sessionV2/messages/schemas.ts
-
 import { z } from 'zod';
 
 import {
@@ -63,8 +59,7 @@ export const ToolUseSchema = z.object({
   thoughtSignature: z.string().optional(), // Gemini thought signature
 });
 
-// For now, this will be only used to send initial file content from the frontend to the daemon.
-// In the future, when we switch off vercel, we'll be able to use this instead of parsedData.
+// Used to send initial PDF content from the client to the daemon.
 export const Base64PDFSourceSchema = z.object({
   type: z.literal(DocumentSourceType.Base64),
   mediaType: z.literal('application/pdf'),
diff --git a/src/protocol/mission-decomposition.ts b/src/protocol/mission-decomposition.ts
@@ -1,6 +1,3 @@
-// Source-of-truth mirror of factory-mono-alpha mission-decomposition schemas.
-// Verbatim copy of packages/common/src/droid/schemas/mission-decomposition.ts.
-
 import { z } from 'zod';
 
 import { CustomModelsSchema } from './custom-models.js';
@@ -134,33 +131,24 @@ export const DismissalRecordSchema = z.object({
 });
 
 // -------------------------
-// On-disk mission artifact schemas (GitHub issue #974)
+// On-disk mission artifact schemas
 //
-// These describe the shape of files the CLI's MissionFileService reads
-// and writes under `{missionDir}/`. They are intentionally stricter than
-// the protocol-level MissionFeatureSchema above: on-disk corruption
-// (a missing `status`, a truncated `state.json`, etc.) is the failure
-// class that drives scheduler-replay bugs, so schema enforcement here is
-// the first line of defense.
+// Describe the shape of files persisted under `{missionDir}/`. These are
+// intentionally stricter than the protocol-level MissionFeatureSchema above:
+// on-disk corruption (missing `status`, truncated state file, etc.) is the
+// failure class schema enforcement is designed to catch early.
 // -------------------------
 
 /**
- * On-disk feature schema. Kept intentionally more permissive than
- * `MissionFeatureSchema` (several list-typed fields are optional here
- * because `MissionFileService.normalizeFeature()` fills them with `[]`
- * defaults after reading). The fields we keep strict are the ones the
- * orchestrator always authors and whose silent regression would cause
- * scheduler-replay bugs: `id`, `description`, `status`.
+ * On-disk feature schema. More permissive than `MissionFeatureSchema` for
+ * list-typed fields (readers default them to `[]`). The required fields are
+ * those the orchestrator always authors and whose silent regression would
+ * lead to scheduler replay errors: `id`, `description`, `status`.
  */
 const OnDiskMissionFeatureSchema = z
   .object({
     id: z.string(),
     description: z.string(),
-    // Required: silent default-to-Pending re-enables the replay bug #974
-    // defends against. Missing status is corruption. Readers may have a
-    // narrow self-heal path for uniformly-legacy files authored by older
-    // CLI builds that never wrote `status`; anything else routes through
-    // the pause/repair flow in MissionRunner.
     status: z.nativeEnum(FeatureStatus),
     skillName: z.string().optional(),
     preconditions: z.array(z.string()).optional(),
@@ -254,10 +242,7 @@ export const MissionAcceptedEntrySchema = BaseProgressLogEntrySchema.extend({
 
 export const MissionPausedEntrySchema = BaseProgressLogEntrySchema.extend({
   type: z.literal(ProgressLogEntryType.MissionPaused),
-  /**
-   * Structured cause when the pause is automatic (e.g. unrecoverable 402).
-   * Absent for user- or runner-initiated pauses.
-   */
+  /** Structured cause when the pause is automatic. Absent for user-initiated pauses. */
   pauseReason: z.nativeEnum(MissionPauseReason).optional(),
 });
 
@@ -304,11 +289,7 @@ export const WorkerFailedEntrySchema = BaseProgressLogEntrySchema.extend({
   spawnId: z.string(),
   exitCode: z.number().optional(),
   reason: z.string(),
-  /**
-   * Structured cause that lets the MissionRunner branch on specific failure
-   * modes (e.g. unrecoverable 402 → auto-pause). Absent means a generic
-   * failure: requeue + return to orchestrator.
-   */
+  /** Structured failure cause used to branch on auto-pause vs requeue. Absent means a generic failure. */
   failureReason: z.nativeEnum(WorkerFailureReason).optional(),
 });
 
diff --git a/src/protocol/model-settings.ts b/src/protocol/model-settings.ts
diff --git a/src/protocol/policy.ts b/src/protocol/policy.ts
diff --git a/src/protocol/selectable-list-item.ts b/src/protocol/selectable-list-item.ts
diff --git a/src/protocol/session-settings-schema.ts b/src/protocol/session-settings-schema.ts
diff --git a/src/protocol/session-settings-types.ts b/src/protocol/session-settings-types.ts
diff --git a/src/protocol/session-source.ts b/src/protocol/session-source.ts
diff --git a/src/protocol/session.ts b/src/protocol/session.ts
diff --git a/src/protocol/settings.ts b/src/protocol/settings.ts
