@getforgeai/protocol 0.1.0-beta.3 → 0.1.0-beta.5

package/dist/constants/effort-level.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generic reasoning-effort scale shared by all agent engines.
+ * Each engine maps it onto its native knob at spawn time (CLI side):
+ *   - Claude Code: --effort low|medium|high|max
+ *   - Codex: model_reasoning_effort (max -> xhigh)
+ *   - OpenCode/Kilo: --variant, clamped per model vendor
+ * "Thinking" is deliberately not a separate toggle: on modern models the
+ * effort level IS the reasoning control.
+ */
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "max"];
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];
+export declare const EFFORT_LEVEL_LABELS: Record<EffortLevel, string>;
+//# sourceMappingURL=effort-level.d.ts.map

package/dist/constants/effort-level.js

@@ -0,0 +1,17 @@
+/**
+ * Generic reasoning-effort scale shared by all agent engines.
+ * Each engine maps it onto its native knob at spawn time (CLI side):
+ *   - Claude Code: --effort low|medium|high|max
+ *   - Codex: model_reasoning_effort (max -> xhigh)
+ *   - OpenCode/Kilo: --variant, clamped per model vendor
+ * "Thinking" is deliberately not a separate toggle: on modern models the
+ * effort level IS the reasoning control.
+ */
+export const EFFORT_LEVELS = ["low", "medium", "high", "max"];
+export const EFFORT_LEVEL_LABELS = {
+    low: "Low",
+    medium: "Medium",
+    high: "High",
+    max: "Max",
+};
+//# sourceMappingURL=effort-level.js.map

package/dist/constants/known-models.d.ts

@@ -0,0 +1,25 @@
+import type { AgentType } from "./agent-type.js";
+export type KnownModelSuggestion = {
+    /** The id to declare (what the engine's model flag/config accepts). */
+    id: string;
+    /** Short human label for UI chips. */
+    label: string;
+    /** Optional availability caveat shown as a hint. */
+    note?: string;
+};
+/**
+ * Curated model suggestions for engines with NO headless listing command
+ * (Claude Code and Codex). OpenCode and Kilo have live catalogs
+ * (`opencode models` / `kilo models`) fetched from the device instead —
+ * see the models:catalog:request socket event.
+ *
+ * Claude Code ids are ALIASES on purpose: they resolve server-side to the
+ * current best version, so declared lists do not go stale, and demand/supply
+ * string-matching stays coherent when everyone uses the same spelling.
+ *
+ * Curated as of 2026-07; revisit when vendors ship new lineups.
+ */
+export declare const KNOWN_MODEL_SUGGESTIONS: Partial<Record<AgentType, KnownModelSuggestion[]>>;
+/** Engines whose catalog can be listed live from the device. */
+export declare const LIVE_CATALOG_ENGINES: readonly AgentType[];
+//# sourceMappingURL=known-models.d.ts.map

package/dist/constants/known-models.js

@@ -0,0 +1,42 @@
+/**
+ * Curated model suggestions for engines with NO headless listing command
+ * (Claude Code and Codex). OpenCode and Kilo have live catalogs
+ * (`opencode models` / `kilo models`) fetched from the device instead —
+ * see the models:catalog:request socket event.
+ *
+ * Claude Code ids are ALIASES on purpose: they resolve server-side to the
+ * current best version, so declared lists do not go stale, and demand/supply
+ * string-matching stays coherent when everyone uses the same spelling.
+ *
+ * Curated as of 2026-07; revisit when vendors ship new lineups.
+ */
+export const KNOWN_MODEL_SUGGESTIONS = {
+    CLAUDE_CODE: [
+        { id: "sonnet", label: "Sonnet" },
+        { id: "opus", label: "Opus", note: "Not available on the Pro plan" },
+        { id: "haiku", label: "Haiku" },
+        {
+            id: "fable",
+            label: "Fable",
+            note: "Requires organization access (server-gated)",
+        },
+        {
+            id: "sonnet[1m]",
+            label: "Sonnet 1M",
+            note: "1M context; usage credits on Pro",
+        },
+    ],
+    CODEX: [
+        { id: "gpt-5.5", label: "GPT-5.5", note: "Recommended default" },
+        { id: "gpt-5.4", label: "GPT-5.4" },
+        { id: "gpt-5.4-mini", label: "GPT-5.4 mini" },
+        { id: "gpt-5.6-sol", label: "GPT-5.6 Sol", note: "Entitlement-gated" },
+        { id: "gpt-5.6-terra", label: "GPT-5.6 Terra" },
+    ],
+};
+/** Engines whose catalog can be listed live from the device. */
+export const LIVE_CATALOG_ENGINES = [
+    "OPENCODE",
+    "KILO",
+];
+//# sourceMappingURL=known-models.js.map

package/dist/events/socket-events.d.ts

@@ -47,6 +47,8 @@ export type TaskUpdatePayload = SocketEventEnvelope & {
     cliDeviceId?: string | null;
     taskGroupId?: string | null;
     taskGroupName?: string | null;
+    /** Task.metadata Json — carries dispatchBlocked ("MODEL_MISMATCH") among app data */
+    metadata?: Record<string, unknown> | null;
     startedAt?: string | null;
     taskBranch?: string | null;
     prUrl?: string | null;
@@ -72,6 +74,14 @@ export type TaskDispatchPayload = SocketEventEnvelope & {
     taskSlug?: string;
     projectSlug?: string;
     repoUrl?: string;
+    /**
+     * Resolved model/effort for the target device's engine
+     * (column -> project -> org demand chain; see ResolvedModelConfigSchema).
+     */
+    modelConfig?: {
+        model?: string;
+        effort?: string;
+    };
 };
 export type CliHeartbeatPayload = SocketEventEnvelope & {
     cliId: string;
@@ -333,6 +343,11 @@ export type WorkflowStepDispatchPayload = SocketEventEnvelope & {
     projectSlug: string;
     conversationHistory?: string;
     hasSnapshot?: boolean;
+    /** Resolved model/effort for the target device (project -> org demand). */
+    modelConfig?: {
+        model?: string;
+        effort?: string;
+    };
 };
 export type WorkflowAgentIdlePayload = SocketEventEnvelope & {
     workflowId: string;
@@ -380,6 +395,11 @@ export type TaskResumePayload = SocketEventEnvelope & {
     projectSlug?: string;
     taskBranch?: string;
     repoUrl?: string;
+    /** Resolved model/effort for the target device (column -> project -> org). */
+    modelConfig?: {
+        model?: string;
+        effort?: string;
+    };
 };
 export type ProjectKanbanConfigPayload = SocketEventEnvelope & {
     columns: {
@@ -399,6 +419,16 @@ export type CliConfigUpdatedPayload = {
      * subsequent agent spawns.
      */
     agentType?: string;
+    /**
+     * Server-owned available-models list per engine, present when the cockpit
+     * edited it. The CLI persists it as its declared model list.
+     */
+    availableModels?: Record<string, string[]>;
+    /**
+     * When true, the org locked the device's model list: the server ignores
+     * CLI-sent lists and `forge config set models` must refuse locally.
+     */
+    modelsLocked?: boolean;
 };
 export type SocketErrorPayload = {
     message: string;
@@ -445,6 +475,18 @@ export type ServerToClientEvents = {
     "workflow:tool-activity": (payload: WorkflowToolActivityPayload) => void;
     "workflow:token-usage": (payload: WorkflowTokenUsagePayload) => void;
     "cli:config:updated": (payload: CliConfigUpdatedPayload) => void;
+    /**
+     * Cockpit → CLI: list the models the device can actually run for an engine
+     * (OpenCode/Kilo run their own catalog command in the agent image; other
+     * engines answer from the curated KNOWN_MODEL_SUGGESTIONS). Ack-based with
+     * a server-side timeout — the container run can take tens of seconds.
+     */
+    "models:catalog:request": (payload: {
+        engine: string;
+    }, callback: (data: {
+        models: string[];
+        error?: string;
+    } | null) => void) => void;
     error: (payload: SocketErrorPayload) => void;
 };
 export type ClientToServerEvents = {

package/dist/index.d.ts

@@ -3,6 +3,10 @@ export type { KanbanColumnConfig } from "./constants/task-status.js";
 export { AGENT_STATUS } from "./constants/agent-status.js";
 export { AGENT_TYPE, AGENT_TYPE_LABELS, DEFAULT_AGENT_TYPE, isAgentType, } from "./constants/agent-type.js";
 export type { AgentType } from "./constants/agent-type.js";
+export { EFFORT_LEVELS, EFFORT_LEVEL_LABELS, } from "./constants/effort-level.js";
+export type { EffortLevel } from "./constants/effort-level.js";
+export { KNOWN_MODEL_SUGGESTIONS, LIVE_CATALOG_ENGINES, } from "./constants/known-models.js";
+export type { KnownModelSuggestion } from "./constants/known-models.js";
 export { CLI_STATUS } from "./constants/cli-status.js";
 export { WORKFLOW_TYPE } from "./constants/workflow-type.js";
 export type { WorkflowType } from "./constants/workflow-type.js";

package/dist/index.js

@@ -2,6 +2,8 @@
 export { KANBAN_SUB_STATUS, DEFAULT_KANBAN_COLUMNS, KANBAN_COLUMN_COLORS, DEFAULT_MAX_REQUEUE, } from "./constants/task-status.js";
 export { AGENT_STATUS } from "./constants/agent-status.js";
 export { AGENT_TYPE, AGENT_TYPE_LABELS, DEFAULT_AGENT_TYPE, isAgentType, } from "./constants/agent-type.js";
+export { EFFORT_LEVELS, EFFORT_LEVEL_LABELS, } from "./constants/effort-level.js";
+export { KNOWN_MODEL_SUGGESTIONS, LIVE_CATALOG_ENGINES, } from "./constants/known-models.js";
 export { CLI_STATUS } from "./constants/cli-status.js";
 export { WORKFLOW_TYPE } from "./constants/workflow-type.js";
 export { WORKFLOW_SCOPE } from "./constants/workflow-scope.js";

package/dist/validation/cli-api.schema.d.ts

@@ -89,6 +89,15 @@ export declare const TaskResumePayloadSchema: z.ZodObject<{
     projectSlug: z.ZodOptional<z.ZodString>;
     taskBranch: z.ZodOptional<z.ZodString>;
     repoUrl: z.ZodOptional<z.ZodString>;
+    modelConfig: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            max: "max";
+        }>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type TaskResumePayload = z.infer<typeof TaskResumePayloadSchema>;
 //# sourceMappingURL=cli-api.schema.d.ts.map

package/dist/validation/cli-api.schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ResolvedModelConfigSchema } from "./model-config.schema.js";
 // --- Heartbeat ---
 export const HeartbeatRequestSchema = z.object({
     cliId: z.string(),
@@ -69,5 +70,6 @@ export const TaskResumePayloadSchema = z.object({
     projectSlug: z.string().optional(),
     taskBranch: z.string().optional(),
     repoUrl: z.string().optional(),
+    modelConfig: ResolvedModelConfigSchema.optional(),
 });
 //# sourceMappingURL=cli-api.schema.js.map

package/dist/validation/index.d.ts

@@ -16,4 +16,6 @@ export { CreateReleaseSchema, UpdateReleaseStatusSchema, ReleaseMergeProgressSch
 export type { CreateRelease, UpdateReleaseStatus, ReleaseMergeProgress, ReleaseReady, ReleaseFinalized, } from "./release.schema.js";
 export { ForgeGetTaskInputSchema, ForgeGetTaskOutputSchema, ForgeUpdateStatusInputSchema, ForgeUpdateStatusOutputSchema, ForgeAskHumanInputSchema, ForgeAskHumanOutputSchema, ForgeRequeueInputSchema, TaskRequeueResponseSchema, TaskAskHumanPayloadSchema, AgentStatusPayloadSchema, AgentStreamPayloadSchema, AgentToolActivityPayloadSchema, ForgeCompleteStepDeliverableSchema, ForgeCompleteStepInputSchema, ForgeCompleteStepPayloadSchema, ForgeCreateTaskGroupInputSchema, ForgeCreateTaskGroupPayloadSchema, ForgeAddGroupDependencyInputSchema, ForgeAddGroupDependencyPayloadSchema, ForgeCreateTaskInputSchema, ForgeCreateTaskPayloadSchema, ForgeAddTaskDependencyInputSchema, ForgeAddTaskDependencyPayloadSchema, ForgeUpdateTaskInputSchema, ForgeUpdateTaskPayloadSchema, ForgeDeleteTaskInputSchema, ForgeDeleteTaskPayloadSchema, ForgeUpdateTaskGroupInputSchema, ForgeUpdateTaskGroupPayloadSchema, ForgeDeleteTaskGroupInputSchema, ForgeDeleteTaskGroupPayloadSchema, ForgeRemoveTaskDependencyInputSchema, ForgeRemoveTaskDependencyPayloadSchema, ForgeRemoveGroupDependencyInputSchema, ForgeRemoveGroupDependencyPayloadSchema, } from "./mcp-tools.schema.js";
 export type { ForgeGetTaskInput, ForgeGetTaskOutput, ForgeUpdateStatusInput, ForgeUpdateStatusOutput, ForgeAskHumanInput, ForgeAskHumanOutput, ForgeRequeueInput, TaskRequeueResponse, TaskAskHumanPayload, AgentStatusPayloadValidated, AgentStreamPayloadValidated, AgentToolActivityPayloadValidated, ForgeCompleteStepDeliverable, ForgeCompleteStepInput, ForgeCompleteStepPayload, ForgeCreateTaskGroupInput, ForgeCreateTaskGroupPayload, ForgeAddGroupDependencyInput, ForgeAddGroupDependencyPayload, ForgeCreateTaskInput, ForgeCreateTaskPayload, ForgeAddTaskDependencyInput, ForgeAddTaskDependencyPayload, ForgeUpdateTaskInput, ForgeUpdateTaskPayload, ForgeDeleteTaskInput, ForgeDeleteTaskPayload, ForgeUpdateTaskGroupInput, ForgeUpdateTaskGroupPayload, ForgeDeleteTaskGroupInput, ForgeDeleteTaskGroupPayload, ForgeRemoveTaskDependencyInput, ForgeRemoveTaskDependencyPayload, ForgeRemoveGroupDependencyInput, ForgeRemoveGroupDependencyPayload, } from "./mcp-tools.schema.js";
+export { EffortLevelSchema, ModelConfigSchema, AvailableModelsSchema, ResolvedModelConfigSchema, } from "./model-config.schema.js";
+export type { ModelConfig, AvailableModels, ResolvedModelConfig, } from "./model-config.schema.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/validation/index.js

@@ -16,4 +16,5 @@ export { WorkflowStreamPayloadSchema, WorkflowStreamEndPayloadSchema, WorkflowMe
 export { CreateReleaseSchema, UpdateReleaseStatusSchema, ReleaseMergeProgressSchema, ReleaseReadySchema, ReleaseFinalizedSchema, } from "./release.schema.js";
 // MCP tool schemas (Story 6.1 + 6.4b + 6.5)
 export { ForgeGetTaskInputSchema, ForgeGetTaskOutputSchema, ForgeUpdateStatusInputSchema, ForgeUpdateStatusOutputSchema, ForgeAskHumanInputSchema, ForgeAskHumanOutputSchema, ForgeRequeueInputSchema, TaskRequeueResponseSchema, TaskAskHumanPayloadSchema, AgentStatusPayloadSchema, AgentStreamPayloadSchema, AgentToolActivityPayloadSchema, ForgeCompleteStepDeliverableSchema, ForgeCompleteStepInputSchema, ForgeCompleteStepPayloadSchema, ForgeCreateTaskGroupInputSchema, ForgeCreateTaskGroupPayloadSchema, ForgeAddGroupDependencyInputSchema, ForgeAddGroupDependencyPayloadSchema, ForgeCreateTaskInputSchema, ForgeCreateTaskPayloadSchema, ForgeAddTaskDependencyInputSchema, ForgeAddTaskDependencyPayloadSchema, ForgeUpdateTaskInputSchema, ForgeUpdateTaskPayloadSchema, ForgeDeleteTaskInputSchema, ForgeDeleteTaskPayloadSchema, ForgeUpdateTaskGroupInputSchema, ForgeUpdateTaskGroupPayloadSchema, ForgeDeleteTaskGroupInputSchema, ForgeDeleteTaskGroupPayloadSchema, ForgeRemoveTaskDependencyInputSchema, ForgeRemoveTaskDependencyPayloadSchema, ForgeRemoveGroupDependencyInputSchema, ForgeRemoveGroupDependencyPayloadSchema, } from "./mcp-tools.schema.js";
+export { EffortLevelSchema, ModelConfigSchema, AvailableModelsSchema, ResolvedModelConfigSchema, } from "./model-config.schema.js";
 //# sourceMappingURL=index.js.map

package/dist/validation/model-config.schema.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+export declare const EffortLevelSchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    max: "max";
+}>;
+/**
+ * Demand-side settings stored on Organization.modelConfig and
+ * Project.modelConfig: the model wanted per engine (ids are engine-specific)
+ * plus a default effort. All fields optional — absent means "inherit"
+ * (project -> org -> device default).
+ */
+export declare const ModelConfigSchema: z.ZodObject<{
+    models: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        CLAUDE_CODE: "CLAUDE_CODE";
+        CODEX: "CODEX";
+        OPENCODE: "OPENCODE";
+        KILO: "KILO";
+    }> & z.core.$partial, z.ZodString>>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        max: "max";
+    }>>;
+}, z.core.$strip>;
+export type ModelConfig = z.infer<typeof ModelConfigSchema>;
+/**
+ * Supply-side declaration stored on CliDevice.availableModels: the models the
+ * device owner has made usable per engine. First entry = the device's default
+ * for that engine. Editable from the CLI unless the org locked it
+ * (CliDevice.modelsLocked), in which case the cockpit owns the list.
+ */
+export declare const AvailableModelsSchema: z.ZodRecord<z.ZodEnum<{
+    CLAUDE_CODE: "CLAUDE_CODE";
+    CODEX: "CODEX";
+    OPENCODE: "OPENCODE";
+    KILO: "KILO";
+}> & z.core.$partial, z.ZodArray<z.ZodString>>;
+export type AvailableModels = z.infer<typeof AvailableModelsSchema>;
+/**
+ * The RESOLVED config riding dispatch payloads (task:dispatch,
+ * workflow:step:dispatch): a single model string for the target device's
+ * engine, plus the effort. Resolution chain (cloud side):
+ * column -> project -> org; a device not declaring the demanded model is
+ * ineligible for the task.
+ */
+export declare const ResolvedModelConfigSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        max: "max";
+    }>>;
+}, z.core.$strip>;
+export type ResolvedModelConfig = z.infer<typeof ResolvedModelConfigSchema>;
+//# sourceMappingURL=model-config.schema.d.ts.map

package/dist/validation/model-config.schema.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { AGENT_TYPE } from "../constants/agent-type.js";
+import { EFFORT_LEVELS } from "../constants/effort-level.js";
+export const EffortLevelSchema = z.enum(EFFORT_LEVELS);
+/**
+ * Demand-side settings stored on Organization.modelConfig and
+ * Project.modelConfig: the model wanted per engine (ids are engine-specific)
+ * plus a default effort. All fields optional — absent means "inherit"
+ * (project -> org -> device default).
+ */
+export const ModelConfigSchema = z.object({
+    models: z
+        .partialRecord(z.enum(AGENT_TYPE), z.string().trim().min(1).max(120))
+        .optional(),
+    effort: EffortLevelSchema.optional(),
+});
+/**
+ * Supply-side declaration stored on CliDevice.availableModels: the models the
+ * device owner has made usable per engine. First entry = the device's default
+ * for that engine. Editable from the CLI unless the org locked it
+ * (CliDevice.modelsLocked), in which case the cockpit owns the list.
+ */
+export const AvailableModelsSchema = z.partialRecord(z.enum(AGENT_TYPE), z.array(z.string().trim().min(1).max(120)).max(20));
+/**
+ * The RESOLVED config riding dispatch payloads (task:dispatch,
+ * workflow:step:dispatch): a single model string for the target device's
+ * engine, plus the effort. Resolution chain (cloud side):
+ * column -> project -> org; a device not declaring the demanded model is
+ * ineligible for the task.
+ */
+export const ResolvedModelConfigSchema = z.object({
+    model: z.string().trim().min(1).max(120).optional(),
+    effort: EffortLevelSchema.optional(),
+});
+//# sourceMappingURL=model-config.schema.js.map

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

@@ -16,6 +16,15 @@ export declare const WorkflowStepDispatchPayloadSchema: z.ZodObject<{
     conversationHistory: z.ZodOptional<z.ZodString>;
     skillSlug: z.ZodOptional<z.ZodString>;
     hasSnapshot: z.ZodOptional<z.ZodBoolean>;
+    modelConfig: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            max: "max";
+        }>>;
+    }, z.core.$strip>>;
     timestamp: z.ZodString;
 }, z.core.$strip>;
 export type WorkflowStepDispatchPayload = z.infer<typeof WorkflowStepDispatchPayloadSchema>;

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ResolvedModelConfigSchema } from "./model-config.schema.js";
 // --- workflow:step:dispatch payload validation (Story 6b.7) ---
 export const WorkflowStepDispatchPayloadSchema = z.object({
     orgId: z.string(),
@@ -17,6 +18,8 @@ export const WorkflowStepDispatchPayloadSchema = z.object({
     conversationHistory: z.string().optional(),
     skillSlug: z.string().optional(),
     hasSnapshot: z.boolean().optional(),
+    /** Resolved model/effort for the target device (column -> project -> org). */
+    modelConfig: ResolvedModelConfigSchema.optional(),
     timestamp: z.string(),
 });
 //# sourceMappingURL=workflow-dispatch.schema.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getforgeai/protocol",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Shared types, constants, Socket.io event definitions and Zod schemas for the ForgeAI CLI/Cloud contract.",
   "license": "Apache-2.0",
   "type": "module",