@getmagical/cli 0.9.1 → 0.9.2

package/README.md

@@ -28,6 +28,31 @@ mgcl automations run-draft --draft-automation-id ... --agent-id ... --idempotenc
 mgcl automations publish --draft-automation-id ...   # non-production only: mgcl refuses against the production API, and the API rejects it too
 ```
 
+## Regression tests
+
+Choose how many historical baseline runs to test per pathway:
+
+```bash
+mgcl regression run \
+  --automation-version <automation-version-id> \
+  --agent-version <agent-version-id> \
+  --runs-per-path 5 \
+  --json
+```
+
+`--runs-per-path` accepts integers from 1 to 20 and defaults to 2. This is an
+upper limit: pathways with fewer eligible historical runs use the available
+runs. Each selected baseline gets 30 replay attempts by default, so five
+baselines produce up to 150 attempts per pathway.
+
+The count applies only when creating a regression test. Repeating the command
+for the same automation and agent version pair returns the existing test;
+changing the count does not expand or rerun it.
+
+`mgcl pathway-regression preview --runs-per-path <count>` remains a historical
+coverage lookup, accepting 1–50 with a default of 2. It does not configure a
+later regression test.
+
 ## Typed classification
 
 Use `mgcl classify` for focused typed judgments over context you already have.

package/dist/index.js

@@ -7889,6 +7889,53 @@ function safeJsonParseWithoutLogging(json) {
   }
 }
 
+// ../common/dist/src/constants/agent-node-presets.js
+var AGENT_NODE_PRESET_TYPES = {
+  minimal: "minimal",
+  browser: "browser",
+  desktop: "desktop",
+  voice: "voice"
+};
+var agentNodePresetOrder = [
+  AGENT_NODE_PRESET_TYPES.minimal,
+  AGENT_NODE_PRESET_TYPES.browser,
+  AGENT_NODE_PRESET_TYPES.desktop,
+  AGENT_NODE_PRESET_TYPES.voice
+];
+var presetToEnvironmentMap = {
+  [AGENT_NODE_PRESET_TYPES.minimal]: ["minimal"],
+  [AGENT_NODE_PRESET_TYPES.browser]: ["browser", "browserCoordinates"],
+  [AGENT_NODE_PRESET_TYPES.desktop]: ["desktop", "desktopApp"],
+  [AGENT_NODE_PRESET_TYPES.voice]: ["voice"]
+};
+var environmentToPresetMap = {
+  minimal: AGENT_NODE_PRESET_TYPES.minimal,
+  browser: AGENT_NODE_PRESET_TYPES.browser,
+  browserCoordinates: AGENT_NODE_PRESET_TYPES.browser,
+  desktop: AGENT_NODE_PRESET_TYPES.desktop,
+  desktopApp: AGENT_NODE_PRESET_TYPES.desktop,
+  voice: AGENT_NODE_PRESET_TYPES.voice
+};
+
+// ../common/dist/src/constants/agents.js
+var defaultAgentNamesByType = {
+  trigger: "Trigger Agent",
+  worker: "Worker Agent",
+  specialist: "Specialist Agent",
+  asset: "Library Asset",
+  code: "Code Agent",
+  extract: "Extract Agent",
+  branch: "Decision Agent",
+  api: "API Agent",
+  specialized: "Specialized Agent",
+  [AGENT_NODE_PRESET_TYPES.minimal]: "Orchestrate Agent",
+  [AGENT_NODE_PRESET_TYPES.browser]: "Browser Agent",
+  [AGENT_NODE_PRESET_TYPES.desktop]: "Desktop Agent",
+  [AGENT_NODE_PRESET_TYPES.voice]: "Voice Agent"
+};
+var PATHWAY_REGRESSION_RUNS_PER_PATH_DEFAULT = 2;
+var PATHWAY_REGRESSION_MAX_RUNS_PER_PATH = 20;
+
 // ../common/dist/src/constants/automation.js
 var AUTOMATION_BRANCH_NAME_MAX_LENGTH = 100;
 var AUTOMATION_BRANCH_NAME_MAX_LENGTH_MESSAGE = `Branch name must be ${AUTOMATION_BRANCH_NAME_MAX_LENGTH} characters or fewer.`;
@@ -13232,7 +13279,7 @@ var magicalBaseModels = [
 ];
 var DEFAULT_MODEL = "gemini-2.5-flash";
 var modelOptionsSchema = z11.object({
-  reasoningEffort: z11.enum(["low", "medium", "high", "xhigh"]).optional().describe("Reasoning effort level for models that support it. Higher effort may produce better results but takes longer. The xhigh level is available on supported OpenAI models."),
+  reasoningEffort: z11.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("Reasoning effort level for models that support it. Higher effort may produce better results but takes longer. The xhigh and max levels are available on supported OpenAI models."),
   temperature: z11.number().min(0).max(2).optional().describe("Controls randomness in model output. 0 is deterministic, higher values (up to 2) increase creativity and randomness."),
   timeoutMs: z11.number().int().min(1).optional().describe("Maximum time to wait for an LLM provider request before failing through the normal result path.")
 });
@@ -14066,6 +14113,15 @@ var baseToolDeclarations = {
       ...reportStopDataSchema.shape
     })
   },
+  handOff: {
+    id: "handOff",
+    description: "Hand off this work item to another root agent of the same automation and end this run.",
+    parameters: z16.object({
+      [COMMON_PARAMETERS_KEY]: DEFAULT_COMMON_PARAMETERS,
+      agentId: z16.string(),
+      input: z16.record(z16.string(), z16.unknown()).optional()
+    })
+  },
   terminateRun: {
     id: "terminateRun",
     description: "End the whole run early using a configured termination code. This stops every agent in the run, not just the current one, and marks the run as early-terminated.",
@@ -15256,6 +15312,7 @@ var baseAgentConfigFieldsSchema = z25.object({
   taskQueue: z25.string().optional().describe("Temporal task queue name for this agent. If specified, queued child agents run on this queue instead of the parent queue."),
   waitUponQueueing: z25.boolean().optional().default(false).describe("If true, wait for queued child agents to complete before proceeding."),
   queueableAgentIds: z25.array(brandedStringValidator("agentId")).optional().default(() => []).describe("List of agent IDs that this agent can queue using the queueAgents tool. Enables the agent to run a new automation with a different agent as the starting point."),
+  handOffAgentIds: z25.array(brandedStringValidator("agentId")).optional().describe("Other root agents in this automation that can receive this agent\u2019s work item through handOff. Requires root agent handoff to be enabled; targets always use the latest version."),
   callableAgentIds: z25.array(brandedStringValidator("agentId")).optional().describe("List of external root agent IDs that this agent can call using the callSpecializedAgent tool. Same-automation callable agents continue to be configured by graph connections."),
   queuedAgentVariables: z25.record(brandedStringValidator("agentId"), z25.record(z25.string(), z25.unknown())).optional().describe("Static automation variable values to pass when this agent queues another automation by target agent ID."),
   checkpoint: z25.object({
@@ -15266,7 +15323,7 @@ var baseAgentConfigFieldsSchema = z25.object({
   additionalSystemPrompt: z25.string().optional().describe("Additional instructions appended to the system prompt for this agent. Combined with automation-level additionalSystemPrompt."),
   // Backlinking metadata for imported agents
   importedFrom: z25.object({
-    automationId: brandedStringValidator("draftAutomationId").describe("ID of the source automation from which this agent was imported."),
+    automationId: brandedStringValidator("automationId").describe("ID of the source automation from which this agent was imported."),
     originalAgentId: brandedStringValidator("agentId").describe("Original agent ID in the source automation.")
   }).optional().describe("Metadata for agents imported from another automation. Used for traceability and updates."),
   ignoreUnstableSessionState: z25.boolean().optional().describe("When true, skips screenshot consistency checks before tool execution. Overrides the automation-level ignoreUnstableSessionState setting."),
@@ -15340,10 +15397,11 @@ var OutcomePayloadSchema = z25.object({
   input: z25.record(z25.string(), z25.unknown()).describe("Input data for the outcome. Maps parameter keys to values."),
   preview: z25.string().describe("Rendered text representation of the outcome.")
 });
+var decisionIncludeScreenshotDescription = "Requires screenshot context from the calling agent. Every way this Decision can be invoked must provide one.";
 var branchAgentConfigSchema = baseAgentConfigFieldsSchema.safeExtend({
   type: z25.literal("branch").describe("Decision agent type - makes decisions to route to different agents."),
   model: agentModelConfigSchema.describe("LLM model configuration for this decision agent."),
-  includeScreenshot: z25.boolean().optional().describe("Whether to include the previous agent's screen state in this decision agent's decision context."),
+  includeScreenshot: z25.boolean().optional().describe(decisionIncludeScreenshotDescription),
   conditionsAndOutcomes: z25.object({
     if: z25.array(z25.object({
       caseName: z25.string().describe("Name of the condition case."),
@@ -15356,7 +15414,7 @@ var branchAgentConfigSchema = baseAgentConfigFieldsSchema.safeExtend({
 var draftBranchAgentConfigSchema = baseAgentConfigFieldsSchema.safeExtend({
   type: z25.literal("branch").describe("Decision agent draft configuration. Allows incomplete conditions and outcomes while the agent is still being authored."),
   model: agentModelConfigSchema.describe("LLM model configuration for this decision agent."),
-  includeScreenshot: z25.boolean().optional().describe("Whether to include the previous agent's screen state in this decision agent's decision context."),
+  includeScreenshot: z25.boolean().optional().describe(decisionIncludeScreenshotDescription),
   conditionsAndOutcomes: z25.object({
     if: z25.array(z25.object({
       caseName: z25.string().describe("Name of the condition case."),
@@ -15589,6 +15647,13 @@ var automationRunConfigBaseSchema = z27.object({
   captureActions: z27.boolean().default(false).describe("When true, attach an action recording while a draft run is paused in takeover mode."),
   runDraftQueuedAgents: z27.boolean().optional().describe("Draft-run-only option. When false, queue-agent actions in the draft run report success without starting downstream queued draft child runs. Omit or true preserves queueing."),
   allowPointOfNoReturnOverride: z27.boolean().optional().describe("Internal rerun authorization. When true, the rerun and its queued descendants may proceed past a point-of-no-return crossing owned by an earlier run."),
+  rootAgentHandoffEnabled: z27.literal(true).optional().describe("Infrastructure-owned capability captured when a work-item-backed run is created. Only these runs can hand off to another root agent."),
+  rootAgentHandoff: z27.object({
+    automationBranchId: z27.uuid().optional().describe("Draft branch captured at run creation. Draft handoffs resolve the current head of this branch."),
+    sourceAutomationRunId: z27.uuid().optional().describe("Predecessor run for an admitted handoff. This run executes the latest version resolved at admission."),
+    successorAutomationRunId: z27.uuid().optional().describe("Accepted handoff receipt. The source can no longer mutate the shared Store once this is recorded."),
+    stopRequestedAt: z27.iso.datetime().optional().describe("Time a stop request was recorded, preventing subsequent handoff admission.")
+  }).optional().describe("Infrastructure-owned durable handoff receipt and stop-intent fence. Updated only while holding the source run lock."),
   pointOfNoReturnGateEnabled: z27.literal(true).optional().describe("Infrastructure-owned rollout marker. PONR is enforced only for run trees created after the gate rollout."),
   sla: automationRunSlaSchema.optional(),
   networkTrafficCapture: networkTrafficCaptureSchema.optional(),
@@ -15622,7 +15687,9 @@ var automationRunStartConfigSchema = automationRunConfigBaseSchema.omit({
   queueResourcePools: true,
   resolvedRunSettings: true,
   resolvedRunSettingsSource: true,
-  pointOfNoReturnGateEnabled: true
+  pointOfNoReturnGateEnabled: true,
+  rootAgentHandoffEnabled: true,
+  rootAgentHandoff: true
 }).extend({
   networkTrafficCapture: networkTrafficCaptureSchema.nullable().optional().describe("Network traffic capture preference for this run. Omit to apply the implicit recording policy, pass null to explicitly disable capture, or pass a record/replay config to explicitly enable capture.")
 });
@@ -20700,7 +20767,7 @@ ${evalRunExportSelection}
 ];
 
 // src/program.ts
-import { Command as Command6, InvalidArgumentError as InvalidArgumentError2, Option as Option7 } from "commander";
+import { Command as Command6, InvalidArgumentError as InvalidArgumentError3, Option as Option7 } from "commander";
 
 // src/api.ts
 import { randomUUID } from "node:crypto";
@@ -22145,8 +22212,12 @@ function createMagicalApiClient({
       agentVersionId,
       automationVersionId,
       impersonatedOrganizationId,
-      organizationId
+      organizationId,
+      runsPerPath
     }) {
+      const query = new URLSearchParams(
+        runsPerPath === void 0 ? {} : { runsPerPath: String(runsPerPath) }
+      );
       const parsedResponse = regressionTestKickoffResponseSchema.safeParse(
         await fetchJson({
           accessToken,
@@ -22155,7 +22226,7 @@ function createMagicalApiClient({
           ...organizationId ? { organizationId } : {},
           path: `/pathway-regression/tests/automation-versions/${encodeURIComponent(
             automationVersionId
-          )}/agent-versions/${encodeURIComponent(agentVersionId)}/run`,
+          )}/agent-versions/${encodeURIComponent(agentVersionId)}/run${query.size > 0 ? `?${query.toString()}` : ""}`,
           init: {
             method: "POST"
           }
@@ -27943,14 +28014,14 @@ async function prepareFileUpload(inputPath, workingDirectory) {
     );
   }
   const checksum = await (async () => {
-    let value = 0;
+    let value = void 0;
     for await (const chunk of createReadStream2(filePath)) {
       if (!(chunk instanceof Uint8Array)) {
         throw new CliError("Upload file stream returned invalid bytes.");
       }
       value = updateS3Crc32Checksum(chunk, value);
     }
-    return value;
+    return value ?? updateS3Crc32Checksum(new Uint8Array());
   })().catch((error) => {
     throw new CliError(`Failed to checksum upload file "${filePath}".`, {
       cause: error
@@ -28977,7 +29048,7 @@ var SESSION_ONLY_API_KEY_MANAGEMENT_COMMANDS = /* @__PURE__ */ new Set([
 
 // src/regression-commands.ts
 import { setTimeout as sleep } from "node:timers/promises";
-import { Command as Command4, Option as Option4 } from "commander";
+import { Command as Command4, InvalidArgumentError as InvalidArgumentError2, Option as Option4 } from "commander";
 var REGRESSION_TEST_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "matched",
   "deviated",
@@ -29104,7 +29175,8 @@ async function handleRegressionRunCommand({
     input: {
       ...authParams,
       agentVersionId: options.agentVersion,
-      automationVersionId: options.automationVersion
+      automationVersionId: options.automationVersion,
+      ...options.runsPerPath === void 0 ? {} : { runsPerPath: options.runsPerPath }
     },
     startRegressionTest: startAgentVersionRegressionTest
   });
@@ -29191,6 +29263,7 @@ function addRegressionCommands({
     `
 ${formatExamples("Examples", [
       "mgcl regression run --automation-version <id> --agent-version <id>",
+      "mgcl regression run --automation-version <id> --agent-version <id> --runs-per-path 5",
       "mgcl regression show <testId>",
       "mgcl regression show <testId> --pathway <pathwayId>"
     ])}`
@@ -29209,6 +29282,19 @@ ${formatExamples("Examples", [
     ).helpGroup("Regression options:").makeOptionMandatory(true)
   ).addOption(
     new Option4("--agent-version <id>", "Agent version to test.").helpGroup("Regression options:").makeOptionMandatory(true)
+  ).addOption(
+    new Option4(
+      "--runs-per-path <count>",
+      `Maximum historical baseline runs per pathway (1\u2013${PATHWAY_REGRESSION_MAX_RUNS_PER_PATH}; default: ${PATHWAY_REGRESSION_RUNS_PER_PATH_DEFAULT}). Applies only to new tests; existing tests are reused unchanged.`
+    ).helpGroup("Regression options:").argParser((rawValue) => {
+      const count = Number(rawValue);
+      if (!Number.isInteger(count) || count < 1 || count > PATHWAY_REGRESSION_MAX_RUNS_PER_PATH) {
+        throw new InvalidArgumentError2(
+          `Expected an integer from 1 to ${PATHWAY_REGRESSION_MAX_RUNS_PER_PATH}.`
+        );
+      }
+      return count;
+    })
   ).action(async function() {
     await handleRegressionRunCommand({
       dependencies,
@@ -31053,7 +31139,7 @@ function parseCommandOptionValue(rawValue, optionSpec) {
     case "number": {
       const parsedNumber = Number(rawValue);
       if (Number.isNaN(parsedNumber)) {
-        throw new InvalidArgumentError2(
+        throw new InvalidArgumentError3(
           `Expected a number for --${optionSpec.flagName}.`
         );
       }
@@ -31065,7 +31151,7 @@ function parseCommandOptionValue(rawValue, optionSpec) {
     case "json": {
       const parsedJson = safeJsonParse(rawValue);
       if (isErr(parsedJson)) {
-        throw new InvalidArgumentError2(
+        throw new InvalidArgumentError3(
           `Expected valid JSON for --${optionSpec.flagName}.`
         );
       }
@@ -31098,7 +31184,7 @@ function createCliCommanderOption(optionSpec, helpGroup) {
 function parsePositiveIntegerOption(rawValue) {
   const parsedValue = Number(rawValue);
   if (!Number.isInteger(parsedValue) || parsedValue < 1) {
-    throw new InvalidArgumentError2("Expected a positive integer.");
+    throw new InvalidArgumentError3("Expected a positive integer.");
   }
   return parsedValue;
 }