@stigmer/cli 3.5.3 → 3.7.0

package/src/resources/mutate-verbs.integration.test.ts

@@ -34,9 +34,15 @@ import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/e
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ScheduleCommandController } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/command_pb";
+import { ScheduleQueryController } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/query_pb";
 import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
 import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import { WorkflowInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { WorkflowInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/command_pb";
+import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
 import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
 import type { Stigmer } from "@stigmer/sdk";
 import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
@@ -85,6 +91,14 @@ const knownChannelApp = create(ChannelAppSchema, {
   metadata: { name: "clinic-meta-app", slug: "clinic-meta-app", org: "acme", id: "chapp_1" },
 });
 
+const knownSchedule = create(ScheduleSchema, {
+  metadata: { name: "daily-fee-reminders", slug: "daily-fee-reminders", org: "acme", id: "sch_1" },
+});
+
+const knownWorkflowInstance = create(WorkflowInstanceSchema, {
+  metadata: { name: "deploy-default", slug: "deploy-default", org: "acme", id: "win_1" },
+});
+
 // Pending execution (cancellable) vs. an already-terminal one.
 const pendingExecution = create(AgentExecutionSchema, {
   metadata: { id: "aex_run" },
@@ -110,8 +124,11 @@ let tagCalls: { workflowId: string; versionHash: string; tag: string }[] = [];
 let datastoreDeletes: { resourceId: string; force: boolean }[] = [];
 let environmentDeletes: { resourceId: string; force: boolean }[] = [];
 let channelAppDeletes: { resourceId: string; force: boolean }[] = [];
-// agent_channel's delete is a typed ID — no force field exists on the wire.
+// agent_channel, schedule, and workflow_instance delete by typed ID — no
+// force field exists on their wire contracts.
 let channelDeleteIds: string[] = [];
+let scheduleDeleteIds: string[] = [];
+let workflowInstanceDeleteIds: string[] = [];
 
 beforeEach(() => {
   cancelCalls = [];
@@ -120,6 +137,8 @@ beforeEach(() => {
   environmentDeletes = [];
   channelAppDeletes = [];
   channelDeleteIds = [];
+  scheduleDeleteIds = [];
+  workflowInstanceDeleteIds = [];
 });
 
 beforeAll(async () => {
@@ -216,6 +235,32 @@ beforeAll(async () => {
       },
     });
 
+    router.service(ScheduleQueryController, {
+      getByReference: (req) => {
+        if (req.slug !== "daily-fee-reminders") throw new ConnectError("schedule not found", Code.NotFound);
+        return knownSchedule;
+      },
+    });
+    router.service(ScheduleCommandController, {
+      delete: (req) => {
+        scheduleDeleteIds.push(req.value);
+        return knownSchedule;
+      },
+    });
+
+    router.service(WorkflowInstanceQueryController, {
+      getByReference: (req) => {
+        if (req.slug !== "deploy-default") throw new ConnectError("workflow instance not found", Code.NotFound);
+        return knownWorkflowInstance;
+      },
+    });
+    router.service(WorkflowInstanceCommandController, {
+      delete: (req) => {
+        workflowInstanceDeleteIds.push(req.value);
+        return knownWorkflowInstance;
+      },
+    });
+
     router.service(WorkflowQueryController, {
       getByReference: (req) => {
         if (req.slug !== "deploy") throw new ConnectError("workflow not found", Code.NotFound);
@@ -306,22 +351,51 @@ describe("delete (standard kinds)", () => {
     expect(classify(err)?.exitCode).toBe(ExitCode.NotFound);
   });
 
+  it("deletes a schedule via its typed ID (tears down the Temporal artifact server-side)", async () => {
+    const plan = await planDelete(client, "schedule", "daily-fee-reminders", "acme");
+    const result = await plan.perform();
+    expect(result.status).toBe("success");
+    expect(result.message).toBe("Schedule deleted successfully");
+    expect(scheduleDeleteIds).toEqual(["sch_1"]);
+  });
+
+  it("deletes a workflow instance via its typed ID", async () => {
+    const plan = await planDelete(client, "workflow-instance", "deploy-default", "acme");
+    const result = await plan.perform();
+    expect(result.status).toBe("success");
+    expect(result.message).toBe("Workflow Instance deleted successfully");
+    expect(workflowInstanceDeleteIds).toEqual(["win_1"]);
+  });
+
   it("rejects an unknown type and lists exactly the wired types", async () => {
     const err = await planDelete(client, "bogus", "x", "acme").catch((e) => e);
     expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
     // The list is derived from DELETE_HANDLERS (+ the two special cases), so
-    // it must name the wired kinds and never the declared-but-unwired ones.
+    // it must name the wired kinds and never the narrowed ones (#354).
     const message = String(err.message);
-    for (const wired of ["datastore", "environment", "agentchannel", "channelapp", "execution", "organization"]) {
+    for (const wired of [
+      "datastore",
+      "environment",
+      "agentchannel",
+      "channelapp",
+      "schedule",
+      "workflowinstance",
+      "execution",
+      "organization",
+    ]) {
       expect(message).toContain(wired);
     }
     expect(message).not.toContain("session");
     expect(message).not.toContain("oauthapp");
   });
 
-  it("rejects a kind that has no delete handler with a usage error", async () => {
+  it("rejects a narrowed kind at the verb gate with a usage error", async () => {
+    // session's delete verb is narrowed out of the matrix
+    // (stigmer/stigmer#354), so the refusal now happens at the verb-support
+    // gate ("does not support") rather than the dispatch fall-through.
     const err = await planDelete(client, "session", "ses_1", "acme").catch((e) => e);
     expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+    expect(String(err.message)).toContain("does not support");
   });
 });
 

package/src/resources/read-verbs.integration.test.ts

@@ -21,6 +21,8 @@ import { ChannelAppSchema } from "@stigmer/protos/ai/stigmer/agentic/channelapp/
 import { ChannelAppQueryController } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/query_pb";
 import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/query_pb";
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ScheduleQueryController } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/query_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
 import { ApiKeyQueryController } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/query_pb";
@@ -142,6 +144,44 @@ const secondChannelApp = create(ChannelAppSchema, {
   },
 });
 
+// Spec/status populated to exercise every SCHEDULE_TABLE column — and the
+// exact condition the table exists to surface (stigmer/stigmer#352): the
+// owner's switch is ON (spec.enabled) while the platform's failure latch is
+// SET (status.paused_reason), two different states with two different
+// remedies.
+const pausedSchedule = create(ScheduleSchema, {
+  apiVersion: "agentic.stigmer.ai/v1",
+  kind: "Schedule",
+  metadata: { name: "daily-fee-reminders", slug: "daily-fee-reminders", org: "acme", id: "sch_1" },
+  spec: {
+    cron: "0 9 * * *",
+    timeZone: "Asia/Kolkata",
+    enabled: true,
+    target: {
+      case: "agent",
+      value: { agentRef: { kind: ApiResourceKind.agent, org: "acme", slug: "clinic-assistant" } },
+    },
+  },
+  status: { pausedReason: "5 consecutive failed runs", consecutiveFailures: 5 },
+});
+
+// Owner-disabled and never fired: empty status, so the row must derive
+// "active" from an absent paused_reason and print no bogus timestamps.
+const disabledSchedule = create(ScheduleSchema, {
+  apiVersion: "agentic.stigmer.ai/v1",
+  kind: "Schedule",
+  metadata: { name: "weekly-digest", slug: "weekly-digest", org: "acme", id: "sch_2" },
+  spec: {
+    cron: "30 6 * * 1",
+    timeZone: "UTC",
+    enabled: false,
+    target: {
+      case: "agent",
+      value: { agentRef: { kind: ApiResourceKind.agent, org: "acme", slug: "reviewer" } },
+    },
+  },
+});
+
 let backend: Http2Server;
 let client: Stigmer;
 const openSessions = new Set<ServerHttp2Session>();
@@ -226,6 +266,20 @@ beforeAll(async () => {
         return { entries: [knownChannelApp, secondChannelApp] };
       },
     });
+    router.service(ScheduleQueryController, {
+      get: (req) => {
+        if (req.value !== "sch_1") throw new ConnectError("schedule not found", Code.NotFound);
+        return pausedSchedule;
+      },
+      getByReference: (req) => {
+        if (req.slug !== "daily-fee-reminders") throw new ConnectError("schedule not found", Code.NotFound);
+        return pausedSchedule;
+      },
+      list: (req) => {
+        if (req.org !== "acme") throw new ConnectError("org is required", Code.InvalidArgument);
+        return { totalCount: 2, items: [pausedSchedule, disabledSchedule] };
+      },
+    });
   };
   backend = createHttp2Server(connectNodeAdapter({ routes }));
   backend.on("session", (session) => {
@@ -341,6 +395,27 @@ describe("get integration", () => {
     });
   });
 
+  it("fetches a schedule by org/slug and renders backend protojson", async () => {
+    const { schema, message } = await fetchResource(client, ApiResourceKind.schedule, {
+      kind: "ref",
+      org: "acme",
+      slug: "daily-fee-reminders",
+    });
+    const rendered = JSON.parse(renderResource(schema, message, "json"));
+    expect(rendered).toEqual(toJson(ScheduleSchema, pausedSchedule, { useProtoFieldName: true }));
+  });
+
+  it("fetches a schedule by ID, exposing the pause diagnosis get exists for", async () => {
+    const { message } = await fetchResource(client, ApiResourceKind.schedule, { kind: "id", id: "sch_1" });
+    // The full resource is where an operator reads WHY the platform paused
+    // a schedule (paused_reason + the streak) — the list table only flags it.
+    expect(JSON.parse(renderResource(ScheduleSchema, message, "json"))).toMatchObject({
+      metadata: { id: "sch_1" },
+      spec: { enabled: true },
+      status: { paused_reason: "5 consecutive failed runs", consecutive_failures: 5 },
+    });
+  });
+
   it("maps a NotFound backend error to ExitCode.NotFound", async () => {
     const err = await fetchResource(client, ApiResourceKind.agent, { kind: "id", id: "missing" }).catch((e) => e);
     const classified = classify(err);
@@ -348,8 +423,11 @@ describe("get integration", () => {
   });
 
   it("rejects an unsupported kind with a usage error", async () => {
-    // session declares Get in the registry but has no get binding — the
-    // canonical still-unwired kind (environment gained a binding).
+    // session's read verbs are narrowed out of the verb matrix
+    // (stigmer/stigmer#354): the command layer refuses at the gate, and this
+    // resource-layer fallback answers anyone bypassing the gate. Wiring
+    // session get requires BOTH the binding and the matrix line — the
+    // registry conformance test enforces the pairing.
     const err = await fetchResource(client, ApiResourceKind.session, { kind: "id", id: "x" }).catch((e) => e);
     expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
   });
@@ -441,10 +519,51 @@ describe("list integration", () => {
     expect(JSON.parse(out)).toEqual([toJson(ChannelAppSchema, knownChannelApp, { useProtoFieldName: true })]);
   });
 
+  it("lists schedules as a table keeping the owner switch and the platform latch distinct", async () => {
+    const out = await listResources(client, ApiResourceKind.schedule, "acme", 50, "table");
+    for (const header of ["ID", "SLUG", "TARGET", "CRON", "TZ", "ENABLED", "STATE"]) {
+      expect(out).toContain(header);
+    }
+    const rows = out.split("\n");
+    // The stigmer/stigmer#352 condition: enabled by the owner, paused by the
+    // platform. Collapsing these into one column would hide exactly this.
+    const pausedRow = rows.find((line) => line.includes("sch_1"));
+    expect(pausedRow).toContain("acme/clinic-assistant");
+    expect(pausedRow).toContain("0 9 * * *");
+    expect(pausedRow).toContain("Asia/Kolkata");
+    expect(pausedRow).toContain("true");
+    expect(pausedRow).toContain("paused");
+    // Owner-disabled with an empty status: derived state is "active" (no
+    // platform latch), and the absent timestamps render nothing bogus.
+    const disabledRow = rows.find((line) => line.includes("sch_2"));
+    expect(disabledRow).toContain("false");
+    expect(disabledRow).toContain("active");
+    expect(disabledRow).not.toContain("paused");
+  });
+
+  it("lists schedules as JSON matching backend protojson", async () => {
+    const out = await listResources(client, ApiResourceKind.schedule, "acme", 50, "json");
+    expect(JSON.parse(out)).toEqual([
+      toJson(ScheduleSchema, pausedSchedule, { useProtoFieldName: true }),
+      toJson(ScheduleSchema, disabledSchedule, { useProtoFieldName: true }),
+    ]);
+  });
+
+  it("refuses to list schedules without an org context, before any RPC", async () => {
+    // ListSchedulesRequest requires org (min_len 1); an unset cloud context
+    // resolves to "". The branch refuses with actionable copy instead of
+    // relaying the server's raw validation error.
+    const err = await listResources(client, ApiResourceKind.schedule, "", 50, "table").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+    expect(String(err.message)).toContain("--org");
+  });
+
   it("rejects a kind whose list is unwired with a usage error", async () => {
-    // agent_share declares List in the registry but has no list branch —
-    // the canonical still-unwired list kind (the three cutover kinds and
-    // environment gained branches).
+    // agent_share's read verbs are narrowed out of the verb matrix
+    // (stigmer/stigmer#354): the command layer refuses at the gate, and this
+    // resource-layer fallback answers anyone bypassing the gate. Wiring
+    // agent_share list requires BOTH the LIST_HANDLERS entry and the matrix
+    // line — the registry conformance test enforces the pairing.
     const err = await listResources(client, ApiResourceKind.agent_share, "acme", 50, "json").catch((e) => e);
     expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
   });

package/src/resources/reference.ts

@@ -86,6 +86,11 @@ export function isSessionId(ref: string): boolean {
   return hasKindPrefix(ref, idPrefixFor(ApiResourceKind.session));
 }
 
+/** True if `ref` carries the schedule ID prefix (`sch_…`/`sch-…`). */
+export function isScheduleId(ref: string): boolean {
+  return hasKindPrefix(ref, idPrefixFor(ApiResourceKind.schedule));
+}
+
 /**
  * True if `ref` starts with ANY known resource-ID prefix (length-agnostic).
  * Mirrors Go's reference.HasResourceIDPrefix: use it to detect *intent* (the

package/src/resources/run/agent-exec.test.ts

@@ -46,6 +46,7 @@ function makePrepared(overrides: Partial<PreparedRun> = {}): PreparedRun {
     model: "",
     autoApproveAll: false,
     mode: "",
+    serviceTier: "",
     ...overrides,
   };
 }

package/src/resources/run/agent-exec.ts

@@ -42,6 +42,7 @@ export async function executeResolvedAgent(input: ResolvedAgentExecInput): Promi
     workspaceEntries: prepared.workspaceEntries,
     model: prepared.model,
     mode: prepared.mode,
+    serviceTier: prepared.serviceTier,
     autoApproveAll: prepared.autoApproveAll,
   });
 

package/src/resources/run/create.test.ts

@@ -4,7 +4,7 @@
 // is faked to capture the exact proto sent to the RPC.
 
 import { describe, expect, it } from "vitest";
-import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { InteractionMode, ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { create } from "@bufbuild/protobuf";
 import {
   LocalPathSourceSchema,
@@ -40,6 +40,7 @@ describe("createAgentExecution", () => {
       workspaceEntries: [],
       model: "claude",
       mode: "plan",
+      serviceTier: "",
       autoApproveAll: true,
     });
 
@@ -67,12 +68,51 @@ describe("createAgentExecution", () => {
       workspaceEntries: [],
       model: "",
       mode: "",
+      serviceTier: "",
       autoApproveAll: false,
     });
     expect(exec.spec?.message).toBe("hi");
     expect(exec.spec?.executionConfig).toBeUndefined();
   });
 
+  it("maps --service-tier fast to the enum (#357)", async () => {
+    const { fn } = fakeController();
+    const exec = await createAgentExecution(fn, {
+      agentId: "agt_1",
+      orgId: "acme",
+      message: "x",
+      runtimeEnv: {},
+      attachments: [],
+      workspaceFileRefs: [],
+      workspaceEntries: [],
+      model: "composer-2.5",
+      mode: "",
+      serviceTier: "fast",
+      autoApproveAll: false,
+    });
+    expect(exec.spec?.executionConfig?.serviceTier).toBe(ServiceTier.FAST);
+  });
+
+  it("maps an explicit --service-tier standard to STANDARD, not UNSPECIFIED", async () => {
+    // Unspecified-vs-explicit-standard is a load-bearing ledger
+    // distinction (#357): an explicit choice must survive to the proto.
+    const { fn } = fakeController();
+    const exec = await createAgentExecution(fn, {
+      agentId: "agt_1",
+      orgId: "acme",
+      message: "x",
+      runtimeEnv: {},
+      attachments: [],
+      workspaceFileRefs: [],
+      workspaceEntries: [],
+      model: "",
+      mode: "",
+      serviceTier: "standard",
+      autoApproveAll: false,
+    });
+    expect(exec.spec?.executionConfig?.serviceTier).toBe(ServiceTier.STANDARD);
+  });
+
   it("leaves InteractionMode unspecified for agent mode", async () => {
     const { fn } = fakeController();
     const exec = await createAgentExecution(fn, {
@@ -85,6 +125,7 @@ describe("createAgentExecution", () => {
       workspaceEntries: [],
       model: "m",
       mode: "agent",
+      serviceTier: "",
       autoApproveAll: false,
     });
     expect(exec.spec?.sessionId).toBe("ses_1");
@@ -110,6 +151,7 @@ describe("createAgentExecution", () => {
       workspaceEntries: [entry],
       model: "",
       mode: "",
+      serviceTier: "",
       autoApproveAll: false,
     });
 
@@ -132,6 +174,7 @@ describe("createAgentExecution", () => {
       workspaceEntries: [],
       model: "",
       mode: "",
+      serviceTier: "",
       autoApproveAll: false,
     });
     expect(exec.spec?.sessionSpec).toBeUndefined();

package/src/resources/run/create.ts

@@ -10,7 +10,7 @@ import type { Client } from "@connectrpc/connect";
 import { create, type DescService } from "@bufbuild/protobuf";
 import { type AgentExecution, AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
-import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { InteractionMode, ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import {
   AgentExecutionSpecSchema,
@@ -29,7 +29,7 @@ import { WorkflowExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/
 import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import type { RuntimeEnv } from "./env.js";
-import type { RunMode } from "./prepare.js";
+import type { RunMode, ServiceTierFlag } from "./prepare.js";
 
 const API_VERSION = "agentic.stigmer.ai/v1";
 
@@ -57,6 +57,7 @@ export interface CreateAgentExecutionInput {
   readonly workspaceEntries: readonly WorkspaceEntry[];
   readonly model: string;
   readonly mode: RunMode;
+  readonly serviceTier: ServiceTierFlag;
   readonly autoApproveAll: boolean;
 }
 
@@ -83,7 +84,7 @@ export async function createAgentExecution(
         input.workspaceEntries.length > 0
           ? create(SessionSpecSchema, { workspaceEntries: [...input.workspaceEntries] })
           : undefined,
-      executionConfig: buildExecutionConfig(input.model, input.mode),
+      executionConfig: buildExecutionConfig(input.model, input.mode, input.serviceTier),
     }),
   });
   return controller(AgentExecutionCommandController).create(execution);
@@ -119,14 +120,22 @@ export async function createWorkflowExecution(
   return controller(WorkflowExecutionCommandController).create(execution);
 }
 
-// Build ExecutionConfig, or undefined when neither flag is set so the backend
+// Build ExecutionConfig, or undefined when no flag is set so the backend
 // applies its defaults. Mirrors Go's buildExecutionConfig (only "plan" maps to a
-// non-default InteractionMode; "agent"/"" leave it unspecified).
-function buildExecutionConfig(model: string, mode: RunMode): ExecutionConfig | undefined {
-  if (model === "" && mode === "") return undefined;
+// non-default InteractionMode; "agent"/"" leave it unspecified). An explicit
+// --service-tier value maps to the enum even for "standard": unspecified vs
+// explicit-standard is a load-bearing ledger distinction (#357).
+function buildExecutionConfig(
+  model: string,
+  mode: RunMode,
+  serviceTier: ServiceTierFlag,
+): ExecutionConfig | undefined {
+  if (model === "" && mode === "" && serviceTier === "") return undefined;
   const cfg = create(ExecutionConfigSchema);
   if (model !== "") cfg.modelName = model;
   if (mode === "plan") cfg.interactionMode = InteractionMode.PLAN;
+  if (serviceTier === "fast") cfg.serviceTier = ServiceTier.FAST;
+  else if (serviceTier === "standard") cfg.serviceTier = ServiceTier.STANDARD;
   return cfg;
 }
 

package/src/resources/run/prepare.test.ts

@@ -5,7 +5,7 @@
 import { describe, expect, it } from "vitest";
 import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { type AgentExecFlags, parseApprovalAction, prepareAgentExec, validateMode } from "./prepare.js";
+import { type AgentExecFlags, parseApprovalAction, prepareAgentExec, validateMode, validateServiceTier } from "./prepare.js";
 
 describe("parseApprovalAction", () => {
   it("maps each accepted value (case-insensitive)", () => {
@@ -35,6 +35,18 @@ describe("validateMode", () => {
   });
 });
 
+describe("validateServiceTier", () => {
+  it("accepts empty, standard, and fast", () => {
+    expect(() => validateServiceTier("")).not.toThrow();
+    expect(() => validateServiceTier("standard")).not.toThrow();
+    expect(() => validateServiceTier("fast")).not.toThrow();
+  });
+
+  it("rejects anything else before a network round trip", () => {
+    expect(() => validateServiceTier("turbo")).toThrow(/must be "standard" or "fast"/);
+  });
+});
+
 const BASE_FLAGS: AgentExecFlags = {
   message: "hi",
   attach: [],
@@ -51,6 +63,7 @@ const BASE_FLAGS: AgentExecFlags = {
   model: "",
   autoApprove: false,
   mode: "",
+  serviceTier: "",
 };
 
 // prepareAgentExec only touches client.agentExecution for attachment uploads;

package/src/resources/run/prepare.ts

@@ -19,6 +19,13 @@ import { localWorkspaceRoots, parseWorkspaceEntries } from "./workspace.js";
 /** The interaction mode requested for the run; "" means the agent default. */
 export type RunMode = "" | "agent" | "plan";
 
+/**
+ * The `--service-tier` flag's value space (#357). Empty means unset —
+ * distinct from an explicit "standard" so the ledger keeps the
+ * unspecified-vs-explicit distinction.
+ */
+export type ServiceTierFlag = "" | "standard" | "fast";
+
 /** Raw agent-execution flags shared by `run` and `draft` (Go's agentExecFlags). */
 export interface AgentExecFlags {
   readonly message: string;
@@ -36,6 +43,7 @@ export interface AgentExecFlags {
   readonly model: string;
   readonly autoApprove: boolean;
   readonly mode: RunMode;
+  readonly serviceTier: ServiceTierFlag;
 }
 
 /**
@@ -54,6 +62,7 @@ export interface PreparedRun {
   readonly model: string;
   readonly autoApproveAll: boolean;
   readonly mode: RunMode;
+  readonly serviceTier: ServiceTierFlag;
 }
 
 /**
@@ -68,6 +77,7 @@ export async function prepareAgentExec(
 ): Promise<PreparedRun> {
   const defaultAction = parseApprovalAction(flags.approveDefault);
   validateMode(flags.mode);
+  validateServiceTier(flags.serviceTier);
 
   const workspaceEntries = parseWorkspaceEntries(flags.workspace, flags.branch, flags.commit);
 
@@ -100,6 +110,7 @@ export async function prepareAgentExec(
     model: flags.model,
     autoApproveAll: flags.autoApprove,
     mode: flags.mode,
+    serviceTier: flags.serviceTier,
   };
 }
 
@@ -137,3 +148,17 @@ export function validateMode(mode: string): asserts mode is RunMode {
     throw new UsageError(`invalid --mode value "${mode}": must be "agent" or "plan"`);
   }
 }
+
+/**
+ * Validate the `--service-tier` flag. Empty means "platform default" (which
+ * resolves to standard — never the provider account default, #357). The
+ * server refuses fast on models without a registry fast variant; this check
+ * only catches spelling errors before a network round trip.
+ */
+export function validateServiceTier(tier: string): asserts tier is ServiceTierFlag {
+  if (tier !== "" && tier !== "standard" && tier !== "fast") {
+    throw new UsageError(
+      `invalid --service-tier value "${tier}": must be "standard" or "fast"`,
+    );
+  }
+}