@getforgeai/protocol 0.1.0-beta.1

package/dist/validation/workflow-branch.schema.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+// --- Workflow Branch Create (Cloud Server → CLI, Story 5c.1) ---
+export const WorkflowBranchCreateSchema = z.object({
+    workflowId: z.string(),
+    sourceBranch: z.string().min(1),
+    baseBranch: z.string().min(1),
+    repoUrl: z.string().min(1),
+});
+// --- Workflow Branch Created (CLI → Cloud Server, Story 5c.1) ---
+export const WorkflowBranchCreatedSchema = z.object({
+    workflowId: z.string(),
+    baseBranch: z.string().min(1),
+    success: z.boolean(),
+    error: z.string().optional(),
+});
+// --- Workflow Branch List Request (Cloud UI → Server → CLI, Story 5c.1) ---
+export const WorkflowBranchListRequestSchema = z.object({
+    repoUrl: z.string().min(1),
+    projectSlug: z.string().min(1).optional(),
+});
+// --- Workflow Branch List Response (CLI → Server → Cloud UI, Story 5c.1) ---
+export const WorkflowBranchListResponseSchema = z.object({
+    branches: z.array(z.string()),
+    defaultBranch: z.string(),
+});
+//# sourceMappingURL=workflow-branch.schema.js.map

package/dist/validation/workflow-dispatch.schema.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const WorkflowStepDispatchPayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    projectId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    stepKey: z.ZodString;
+    stepTitle: z.ZodString;
+    stepCommand: z.ZodOptional<z.ZodString>;
+    conversationId: z.ZodString;
+    repoUrl: z.ZodOptional<z.ZodString>;
+    projectSlug: z.ZodString;
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    sourceBranch: z.ZodOptional<z.ZodString>;
+    conversationHistory: z.ZodOptional<z.ZodString>;
+    skillSlug: z.ZodOptional<z.ZodString>;
+    hasSnapshot: z.ZodOptional<z.ZodBoolean>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowStepDispatchPayload = z.infer<typeof WorkflowStepDispatchPayloadSchema>;
+//# sourceMappingURL=workflow-dispatch.schema.d.ts.map

package/dist/validation/workflow-dispatch.schema.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+// --- workflow:step:dispatch payload validation (Story 6b.7) ---
+export const WorkflowStepDispatchPayloadSchema = z.object({
+    orgId: z.string(),
+    projectId: z.string(),
+    workflowId: z.string(),
+    stepId: z.string(),
+    stepKey: z.string(),
+    stepTitle: z.string(),
+    stepCommand: z.string().optional(),
+    conversationId: z.string().min(1),
+    repoUrl: z.string().optional(),
+    projectSlug: z.string(),
+    workflowSlug: z.string().optional(),
+    baseBranch: z.string().optional(),
+    sourceBranch: z.string().optional(),
+    conversationHistory: z.string().optional(),
+    skillSlug: z.string().optional(),
+    hasSnapshot: z.boolean().optional(),
+    timestamp: z.string(),
+});
+//# sourceMappingURL=workflow-dispatch.schema.js.map

package/dist/validation/workflow-merge.schema.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+export declare const WorkflowMergeTaskPrCreateSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    taskBranch: z.ZodString;
+    workflowBaseBranch: z.ZodString;
+    repoUrl: z.ZodString;
+    prTitle: z.ZodString;
+    prBody: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowMergeTaskPrCreate = z.infer<typeof WorkflowMergeTaskPrCreateSchema>;
+export declare const WorkflowMergeTaskPrCreatedSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    prUrl: z.ZodOptional<z.ZodString>;
+    prNumber: z.ZodOptional<z.ZodNumber>;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowMergeTaskPrCreated = z.infer<typeof WorkflowMergeTaskPrCreatedSchema>;
+export declare const WorkflowMergeFinalPrCreateSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    workflowBranch: z.ZodString;
+    sourceBranch: z.ZodString;
+    repoUrl: z.ZodString;
+    prTitle: z.ZodString;
+    prBody: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowMergeFinalPrCreate = z.infer<typeof WorkflowMergeFinalPrCreateSchema>;
+export declare const WorkflowMergeFinalPrCreatedSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    prUrl: z.ZodOptional<z.ZodString>;
+    prNumber: z.ZodOptional<z.ZodNumber>;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowMergeFinalPrCreated = z.infer<typeof WorkflowMergeFinalPrCreatedSchema>;
+export declare const WorkflowMergeExecuteSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    prNumber: z.ZodNumber;
+    mergeStrategy: z.ZodEnum<{
+        merge: "merge";
+        squash: "squash";
+        rebase: "rebase";
+    }>;
+    repoUrl: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowMergeExecute = z.infer<typeof WorkflowMergeExecuteSchema>;
+export declare const WorkflowMergeExecutedSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowMergeExecuted = z.infer<typeof WorkflowMergeExecutedSchema>;
+export declare const WorkflowMergeCleanupSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    workflowBranch: z.ZodString;
+    repoUrl: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowMergeCleanup = z.infer<typeof WorkflowMergeCleanupSchema>;
+export declare const WorkflowMergeCleanedSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowMergeCleaned = z.infer<typeof WorkflowMergeCleanedSchema>;
+//# sourceMappingURL=workflow-merge.schema.d.ts.map

package/dist/validation/workflow-merge.schema.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+// --- Task PR Create (Cloud Server → CLI, Story 5c.3) ---
+export const WorkflowMergeTaskPrCreateSchema = z.object({
+    taskId: z.string(),
+    taskBranch: z.string().min(1),
+    workflowBaseBranch: z.string().min(1),
+    repoUrl: z.string().min(1),
+    prTitle: z.string().min(1),
+    prBody: z.string().optional(),
+});
+// --- Task PR Created (CLI → Cloud Server, Story 5c.3) ---
+export const WorkflowMergeTaskPrCreatedSchema = z.object({
+    taskId: z.string(),
+    prUrl: z.string().optional(),
+    prNumber: z.number().int().optional(),
+    success: z.boolean(),
+    error: z.string().optional(),
+});
+// --- Final PR Create (Cloud Server → CLI, Story 5c.3) ---
+export const WorkflowMergeFinalPrCreateSchema = z.object({
+    workflowId: z.string(),
+    workflowBranch: z.string().min(1),
+    sourceBranch: z.string().min(1),
+    repoUrl: z.string().min(1),
+    prTitle: z.string().min(1),
+    prBody: z.string().optional(),
+});
+// --- Final PR Created (CLI → Cloud Server, Story 5c.3) ---
+export const WorkflowMergeFinalPrCreatedSchema = z.object({
+    workflowId: z.string(),
+    prUrl: z.string().optional(),
+    prNumber: z.number().int().optional(),
+    success: z.boolean(),
+    error: z.string().optional(),
+});
+// --- Merge Execute (Cloud Server → CLI, Story 5c.3) ---
+export const WorkflowMergeExecuteSchema = z.object({
+    workflowId: z.string(),
+    prNumber: z.number().int(),
+    mergeStrategy: z.enum(["merge", "squash", "rebase"]),
+    repoUrl: z.string().min(1),
+});
+// --- Merge Executed (CLI → Cloud Server, Story 5c.3) ---
+export const WorkflowMergeExecutedSchema = z.object({
+    workflowId: z.string(),
+    success: z.boolean(),
+    error: z.string().optional(),
+});
+// --- Merge Cleanup (Cloud Server → CLI, Story 5c.3) ---
+export const WorkflowMergeCleanupSchema = z.object({
+    workflowId: z.string(),
+    workflowBranch: z.string().min(1),
+    repoUrl: z.string().min(1),
+});
+// --- Merge Cleaned (CLI → Cloud Server, Story 5c.3) ---
+export const WorkflowMergeCleanedSchema = z.object({
+    workflowId: z.string(),
+    success: z.boolean(),
+    error: z.string().optional(),
+});
+//# sourceMappingURL=workflow-merge.schema.js.map

package/dist/validation/workflow-stream.schema.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+export declare const WorkflowStreamPayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    conversationId: z.ZodString;
+    messageId: z.ZodString;
+    chunk: z.ZodString;
+    index: z.ZodNumber;
+    turnIndex: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowStreamPayloadValidated = z.infer<typeof WorkflowStreamPayloadSchema>;
+export declare const WorkflowStreamEndPayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    conversationId: z.ZodString;
+    messageId: z.ZodString;
+    finalContent: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowStreamEndPayloadValidated = z.infer<typeof WorkflowStreamEndPayloadSchema>;
+export declare const WorkflowMessagePayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    conversationId: z.ZodString;
+    messageId: z.ZodString;
+    content: z.ZodString;
+    role: z.ZodEnum<{
+        USER: "USER";
+        ASSISTANT: "ASSISTANT";
+        SYSTEM: "SYSTEM";
+    }>;
+    command: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowMessagePayloadValidated = z.infer<typeof WorkflowMessagePayloadSchema>;
+export declare const WorkflowAgentIdlePayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    idleUntil: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowAgentIdlePayloadValidated = z.infer<typeof WorkflowAgentIdlePayloadSchema>;
+export declare const WorkflowAgentTimeoutPayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowAgentTimeoutPayloadValidated = z.infer<typeof WorkflowAgentTimeoutPayloadSchema>;
+export declare const WorkflowAgentDismissPayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowAgentDismissPayloadValidated = z.infer<typeof WorkflowAgentDismissPayloadSchema>;
+export declare const WorkflowToolActivityPayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    toolName: z.ZodString;
+    toolDetail: z.ZodString;
+    toolUseId: z.ZodOptional<z.ZodString>;
+    parentToolUseId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowToolActivityPayloadValidated = z.infer<typeof WorkflowToolActivityPayloadSchema>;
+export declare const WorkflowTokenUsagePayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowTokenUsagePayloadValidated = z.infer<typeof WorkflowTokenUsagePayloadSchema>;
+export declare const WorkflowQuestionOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const WorkflowQuestionSchema: z.ZodObject<{
+    question: z.ZodString;
+    header: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    multiSelect: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const WorkflowQuestionPayloadSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    workflowId: z.ZodString;
+    stepId: z.ZodString;
+    conversationId: z.ZodString;
+    questions: z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        header: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        multiSelect: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowQuestionPayloadValidated = z.infer<typeof WorkflowQuestionPayloadSchema>;
+//# sourceMappingURL=workflow-stream.schema.d.ts.map

package/dist/validation/workflow-stream.schema.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+// --- workflow:stream payload validation (Story 6b.8) ---
+export const WorkflowStreamPayloadSchema = z.object({
+    orgId: z.string().min(1),
+    workflowId: z.string().min(1),
+    stepId: z.string().min(1),
+    conversationId: z.string().min(1),
+    messageId: z.string().min(1),
+    chunk: z.string(),
+    index: z.number(),
+    /** Groups text chunks from the same API turn (incremented on message_start) */
+    turnIndex: z.number().int().min(0).optional(),
+    timestamp: z.string().min(1),
+});
+// --- workflow:stream:end payload validation (Story 6b.8) ---
+export const WorkflowStreamEndPayloadSchema = z.object({
+    orgId: z.string().min(1),
+    workflowId: z.string().min(1),
+    stepId: z.string().min(1),
+    conversationId: z.string().min(1),
+    messageId: z.string().min(1),
+    finalContent: z.string().min(1),
+    timestamp: z.string().min(1),
+});
+// --- workflow:message payload validation (Story 6b.8) ---
+export const WorkflowMessagePayloadSchema = z.object({
+    orgId: z.string().min(1),
+    workflowId: z.string().min(1),
+    stepId: z.string().min(1),
+    conversationId: z.string().min(1),
+    messageId: z.string().min(1),
+    content: z.string().min(1),
+    role: z.enum(["USER", "ASSISTANT", "SYSTEM"]),
+    command: z.string().optional(),
+    timestamp: z.string().min(1),
+});
+// --- workflow:agent:idle payload validation ---
+export const WorkflowAgentIdlePayloadSchema = z.object({
+    orgId: z.string(),
+    workflowId: z.string(),
+    stepId: z.string(),
+    idleUntil: z.string(),
+    timestamp: z.string(),
+});
+// --- workflow:agent:timeout payload validation ---
+export const WorkflowAgentTimeoutPayloadSchema = z.object({
+    orgId: z.string(),
+    workflowId: z.string(),
+    stepId: z.string(),
+    timestamp: z.string(),
+});
+// --- workflow:agent:dismiss payload validation ---
+export const WorkflowAgentDismissPayloadSchema = z.object({
+    orgId: z.string(),
+    workflowId: z.string(),
+    stepId: z.string(),
+    timestamp: z.string(),
+});
+// --- workflow:tool-activity payload validation (ephemeral, not persisted) ---
+export const WorkflowToolActivityPayloadSchema = z.object({
+    orgId: z.string().min(1),
+    workflowId: z.string().min(1),
+    stepId: z.string().min(1),
+    toolName: z.string().min(1),
+    toolDetail: z.string().max(500),
+    /** For Agent tool_use blocks: the block's own id */
+    toolUseId: z.string().optional(),
+    /** For sub-agent tools: the parent Agent tool_use id */
+    parentToolUseId: z.string().optional(),
+    timestamp: z.string().min(1),
+});
+// --- workflow:token-usage payload validation (ephemeral, not persisted) ---
+export const WorkflowTokenUsagePayloadSchema = z.object({
+    orgId: z.string().min(1),
+    workflowId: z.string().min(1),
+    stepId: z.string().min(1),
+    inputTokens: z.number().int().min(0),
+    outputTokens: z.number().int().min(0),
+    timestamp: z.string().min(1),
+});
+// --- workflow:question payload validation (AskUserQuestion interactive form) ---
+export const WorkflowQuestionOptionSchema = z.object({
+    label: z.string().min(1),
+    description: z.string().optional(),
+});
+export const WorkflowQuestionSchema = z.object({
+    question: z.string().min(1),
+    header: z.string().optional(),
+    options: z.array(WorkflowQuestionOptionSchema).optional(),
+    multiSelect: z.boolean().optional(),
+});
+export const WorkflowQuestionPayloadSchema = z.object({
+    orgId: z.string().min(1),
+    workflowId: z.string().min(1),
+    stepId: z.string().min(1),
+    conversationId: z.string().min(1),
+    questions: z.array(WorkflowQuestionSchema).min(1),
+    timestamp: z.string().min(1),
+});
+//# sourceMappingURL=workflow-stream.schema.js.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@getforgeai/protocol",
+  "version": "0.1.0-beta.1",
+  "description": "Shared types, constants, Socket.io event definitions and Zod schemas for the ForgeAI CLI/Cloud contract.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://forgeai-production-382c.up.railway.app/docs",
+  "bugs": {
+    "url": "https://forgeai-production-382c.up.railway.app/contact"
+  },
+  "keywords": [
+    "forgeai",
+    "protocol",
+    "types",
+    "zod",
+    "socket.io"
+  ],
+  "peerDependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsc",
+    "ts": "tsc --noEmit",
+    "test": "vitest",
+    "test:ci": "vitest run"
+  }
+}