@getmagical/cli 0.1.12 → 0.1.15

package/dist/index.js

@@ -6590,7 +6590,7 @@ import { Help } from "commander";
 var EMPTY_VALUE = "-";
 var TABLE_GAP = "  ";
 function applyStyle(value, style, enabled = true) {
-  if (!enabled) {
+  if (!enabled || typeof styleText !== "function") {
     return value;
   }
   return styleText(style, value);
@@ -6885,2028 +6885,2147 @@ function getErrorMessage(error) {
 }
 
 // src/program.ts
+import { readFile as readFile4 } from "fs/promises";
 import path6 from "path";
 
-// ../mcp-registry/src/operation-specs.ts
+// ../common/dist/src/stdlib/json.util.js
+var import_ts_essentials = __toESM(require_dist(), 1);
+
+// ../common/dist/src/stdlib/result.util.js
 import { z } from "zod";
 
-// ../mcp-registry/src/operation-spec.ts
-function stripLeadingGraphqlComments(document) {
-  return document.replace(/^(?:\s*#.*\n)+/u, "").trimStart();
+// ../common/dist/src/stdlib/error-user-facing.js
+var USER_FACING_STATUS_MESSAGES = /* @__PURE__ */ new Map([
+  [400, "Bad Request"],
+  [401, "Unauthorized"],
+  [403, "Forbidden"],
+  [404, "Not Found"],
+  [500, "Internal Server Error"],
+  [503, "Service Unavailable"]
+]);
+var USER_FACING_DEFAULT_ACTIONS = /* @__PURE__ */ new Map([
+  [400, "Review the request payload and retry."],
+  [401, "Authenticate and retry the request."],
+  [403, "Verify your permissions and retry the request."],
+  [404, "Verify the requested resource exists and retry."],
+  [
+    500,
+    "Retry the request. If this keeps happening, contact support and share the correlation ID."
+  ],
+  [
+    503,
+    "Retry the request after a brief delay. If this keeps happening, contact support and share the correlation ID."
+  ]
+]);
+var USER_FACING_FALLBACK_CODES = /* @__PURE__ */ new Map([
+  [400, "BAD_REQUEST"],
+  [401, "UNAUTHORIZED"],
+  [403, "FORBIDDEN"],
+  [404, "NOT_FOUND"],
+  [500, "INTERNAL_SERVER_ERROR"],
+  [503, "SERVICE_UNAVAILABLE"]
+]);
+function isCustomerUsageError(appError) {
+  return appError.categories.includes("customer_usage");
 }
-function assertDocumentMatchesOperation({
-  document,
-  kind,
-  operationName
-}) {
-  const normalizedDocument = stripLeadingGraphqlComments(document);
-  const match = /^(?<actualKind>query|mutation)\s+(?<actualOperationName>[_A-Za-z][_0-9A-Za-z]*)/u.exec(
-    normalizedDocument
-  );
-  const actualKind = match?.groups?.["actualKind"];
-  const actualOperationName = match?.groups?.["actualOperationName"];
-  if (!actualKind || !actualOperationName) {
-    throw new Error(
-      `Operation "${operationName}" is missing a top-level GraphQL ${kind} definition.`
-    );
+function getStatusCodeFromAppErrorCode(code) {
+  if (typeof code !== "number" || !Number.isInteger(code)) {
+    return void 0;
   }
-  if (actualKind !== kind || actualOperationName !== operationName) {
-    throw new Error(
-      `Operation "${operationName}" does not match its GraphQL document (${actualKind} ${actualOperationName}).`
-    );
+  if (code >= 400 && code <= 599) {
+    return code;
   }
+  return void 0;
 }
-function createOperationSpec(spec) {
-  assertDocumentMatchesOperation(spec);
-  return spec;
+function getStatusFamilyFallbackCode(statusCode) {
+  if (statusCode >= 400 && statusCode <= 499) {
+    return 400;
+  }
+  return 500;
 }
-
-// ../mcp-registry/src/operation-specs.ts
-function stringOption({
-  description,
-  flagName,
-  inputKey,
-  required = false
-}) {
-  return {
-    description,
-    flagName,
-    inputKey,
-    required,
-    valueType: "string"
-  };
+function getStatusMessage(statusCode) {
+  const directMessage = USER_FACING_STATUS_MESSAGES.get(statusCode);
+  if (directMessage !== void 0) {
+    return directMessage;
+  }
+  return getStatusFamilyFallbackCode(statusCode) === 400 ? "Bad Request" : "Internal Server Error";
 }
-function numberOption({
-  description,
-  flagName,
-  inputKey,
-  required = false
-}) {
-  return {
-    description,
-    flagName,
-    inputKey,
-    required,
-    valueType: "number"
-  };
+function getDefaultSuggestedAction(statusCode) {
+  const directAction = USER_FACING_DEFAULT_ACTIONS.get(statusCode);
+  if (directAction !== void 0) {
+    return directAction;
+  }
+  return getStatusFamilyFallbackCode(statusCode) === 400 ? "Review the request payload and retry." : "Retry the request. If this keeps happening, contact support and share the correlation ID.";
 }
-function booleanOption({
-  description,
-  flagName,
-  inputKey
-}) {
-  return {
-    description,
-    flagName,
-    inputKey,
-    valueType: "boolean"
-  };
+function getFallbackErrorCode(statusCode) {
+  const directCode = USER_FACING_FALLBACK_CODES.get(statusCode);
+  if (directCode !== void 0) {
+    return directCode;
+  }
+  return getStatusFamilyFallbackCode(statusCode) === 400 ? "BAD_REQUEST" : "INTERNAL_SERVER_ERROR";
 }
-function stringArrayOption({
-  description,
-  flagName,
-  inputKey,
-  required = false
-}) {
-  return {
-    description,
-    flagName,
-    inputKey,
-    required,
-    valueHint: "comma-separated",
-    valueType: "string-array"
-  };
+function shouldExposeMessage({ appError, statusCode }) {
+  if (statusCode >= 500) {
+    return false;
+  }
+  return isCustomerUsageError(appError);
 }
-function jsonOption({
-  description,
-  flagName,
-  inputKey,
-  required = false
-}) {
-  return {
-    description,
-    flagName,
-    inputKey,
-    required,
-    valueHint: "JSON",
-    valueType: "json"
-  };
+function resolveApiMessage({ appError, statusCode }) {
+  if (!shouldExposeMessage({ appError, statusCode })) {
+    return getStatusMessage(statusCode);
+  }
+  const trimmedMessage = appError.message.trim();
+  if (trimmedMessage.length > 0) {
+    return trimmedMessage;
+  }
+  return getStatusMessage(statusCode);
 }
-var jsonObjectSchema = z.record(z.string(), z.unknown());
-var agentBrowserProviderOptionsSelection = `            browserbase {
-              advancedStealth
-              contextId
-              extensionId
-              instanceSize
-              blockAds
-              solveCaptchas
-              viewport {
-                width
-                height
-              }
-            }
-            agentCore {
-              viewport {
-                width
-                height
-              }
-              enableWebBotAuth
-            }
-            local {
-              viewport {
-                width
-                height
-              }
-            }
-            hyperbrowser {
-              viewport {
-                width
-                height
-              }
-            }
-            steel {
-              extensionIds
-              region
-              solveCaptcha
-              viewport {
-                width
-                height
-              }
-            }`;
-var agentEnvironmentOptionsSelection = `      environmentOptions {
-        __typename
-        ... on AgentConfig_environmentOptions_Browser {
-          environment
-          maxMediaToIncludeInMemory
-          saveAuthCookiesAfterRun
-          startingUrl
-          browserProvider
-          browserProviderOptions {
-${agentBrowserProviderOptionsSelection}
-          }
-        }
-        ... on AgentConfig_environmentOptions_Browsercoordinates {
-          environment
-          maxMediaToIncludeInMemory
-          saveAuthCookiesAfterRun
-          startingUrl
-          browserProvider
-          browserProviderOptions {
-${agentBrowserProviderOptionsSelection}
-          }
-        }
-        ... on AgentConfig_environmentOptions_Desktop {
-          environment
-          browserProvider
-          browserProviderOptions {
-${agentBrowserProviderOptionsSelection}
-          }
-          maxMediaToIncludeInMemory
-          startingUrl
-          useCopyPasteForTyping
-        }
-        ... on AgentConfig_environmentOptions_Desktopapp {
-          environment
-          maxMediaToIncludeInMemory
-        }
-        ... on AgentConfig_environmentOptions_Minimal {
-          environment
-        }
-      }`;
-var agentLimitationsSelection = `      limitations {
-        maxDurationSeconds
-        maxToolCalls
-        allowedUrlRegexes
-      }`;
-var operationSpecs = [
-  createOperationSpec({
-    operationName: "GetAgents",
-    kind: "query",
-    inputSchema: z.object({
-      ids: z.array(z.string().min(1)).min(1)
-    }),
-    cli: {
-      name: "get-agents",
-      path: ["agents", "get"],
-      description: "Fetch one or more agents with config and schema fields.",
-      resultKey: "agents",
-      options: [
-        stringArrayOption({
-          inputKey: "ids",
-          flagName: "ids",
-          description: "Agent IDs.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "agents.graphql" },
-    document: `# Query to fetch multiple agents with all fields
-# Includes nested environment and limitation config fields
-query GetAgents($ids: [ID!]!) {
-  agents(ids: $ids) {
-    id
-    name
-    description
-    instructions
-    organizationId
-    createdAt
-    updatedAt
-    sourceAgentId
-    inputSchema
-    outputSchema
-    config {
-      type
-      language
-      model
-      tools
-      maxSessionMessages
-${agentEnvironmentOptionsSelection}
-${agentLimitationsSelection}
-      commonParametersSchema
-      taskQueue
-      waitUponQueueing
-      queueableAgentIds
-      additionalSystemPrompt
-      ignoreUnstableSessionState
-    }
-    childAgentIds
-    }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAgentVersion",
-    kind: "query",
-    inputSchema: z.object({
-      agentId: z.string().min(1),
-      versionId: z.string().min(1)
-    }),
-    cli: {
-      name: "get-agent-version",
-      path: ["agents", "versions", "get"],
-      description: "Fetch one saved version for an agent.",
-      resultKey: "agentVersion",
-      options: [
-        stringOption({
-          inputKey: "agentId",
-          flagName: "agent-id",
-          description: "Agent ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "versionId",
-          flagName: "version-id",
-          description: "Agent version ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "agentVersion.graphql" },
-    document: `# Query to fetch a specific saved version for an agent
-query GetAgentVersion($agentId: ID!, $versionId: ID!) {
-  agentVersion(agentId: $agentId, versionId: $versionId) {
-    id
-    agentId
-    sequence
-    name
-    description
-    instructions
-    instructionsMode
-    instructionsDoc
-    updaterUserId
-    createdAt
-    updatedAt
-    inputSchema
-    outputSchema
-    config {
-      type
-      language
-      model
-      tools
-      maxSessionMessages
-${agentEnvironmentOptionsSelection}
-${agentLimitationsSelection}
-      commonParametersSchema
-      taskQueue
-      waitUponQueueing
-      queueableAgentIds
-      additionalSystemPrompt
-      ignoreUnstableSessionState
-    }
-    isCurrent
+function resolveApiErrorCode({ appError, statusCode }) {
+  if (!shouldExposeMessage({ appError, statusCode })) {
+    return getFallbackErrorCode(statusCode);
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAgentVersions",
-    kind: "query",
-    inputSchema: z.object({
-      agentId: z.string().min(1)
-    }),
-    cli: {
-      name: "get-agent-versions",
-      path: ["agents", "versions", "list"],
-      description: "Fetch version history for an agent.",
-      resultKey: "agentVersions",
-      options: [
-        stringOption({
-          inputKey: "agentId",
-          flagName: "agent-id",
-          description: "Agent ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "agentVersions.graphql" },
-    document: `# Query to fetch version history metadata for an agent
-query GetAgentVersions($agentId: ID!) {
-  agentVersions(agentId: $agentId) {
-    id
-    sequence
-    name
-    description
-    updaterUserId
-    createdAt
-    updatedAt
-    isCurrent
+  return normalizeUserFacingErrorCode({
+    type: appError.type,
+    fallbackCode: getFallbackErrorCode(statusCode)
+  });
+}
+function resolveSuggestedAction({ appError, statusCode }) {
+  const trimmedSuggestedAction = appError.suggestedAction?.trim();
+  if (shouldExposeMessage({ appError, statusCode }) && trimmedSuggestedAction) {
+    return trimmedSuggestedAction;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "DiffAgentVersion",
-    kind: "query",
-    inputSchema: z.object({
-      agentId: z.string().min(1),
-      versionId: z.string().min(1),
-      compareVersionId: z.string().min(1).optional()
-    }),
-    cli: {
-      name: "diff-agent-version",
-      path: ["agents", "versions", "diff"],
-      description: "Diff one agent version against another version or the current latest version.",
-      resultKey: "agentVersionDiff",
-      options: [
-        stringOption({
-          inputKey: "agentId",
-          flagName: "agent-id",
-          description: "Agent ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "versionId",
-          flagName: "version-id",
-          description: "Source agent version ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "compareVersionId",
-          flagName: "compare-version-id",
-          description: "Optional target version ID. Defaults to the current latest version."
-        })
-      ]
-    },
-    mcp: { fileName: "agentVersionDiff.graphql" },
-    document: `# Query to diff one agent version against another or the current latest version
-query DiffAgentVersion(
-  $agentId: ID!
-  $versionId: ID!
-  $compareVersionId: ID
-) {
-  agentVersionDiff(
-    agentId: $agentId
-    versionId: $versionId
-    compareVersionId: $compareVersionId
-  ) {
-    agentId
-    fromVersionId
-    toVersionId
-    hasChanges
-    changes {
-      field
-      oldValue
-      newValue
-    }
+  return getDefaultSuggestedAction(statusCode);
+}
+function getZodIssuesFromCause(cause, maxDepth = 10) {
+  if (maxDepth < 0 || typeof cause !== "object" || cause === null) {
+    return void 0;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAgentRun",
-    kind: "query",
-    inputSchema: z.object({
-      id: z.string().min(1)
-    }),
-    cli: {
-      name: "get-agent-run",
-      path: ["agent-runs", "get"],
-      description: "Fetch a single agent run.",
-      resultKey: "agentRun",
-      options: [
-        stringOption({
-          inputKey: "id",
-          flagName: "id",
-          description: "Agent run ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "agentRun.graphql" },
-    document: `# Query a single agent run
-query GetAgentRun($id: ID!) {
-  agentRun(id: $id) {
-    id
-    agentVersionId
-    agentName
-    status
-    statusDetail
-    isChildAgent
-    input
-    startedAt
-    finishedAt
-    parentAgentRunId
+  if ("issues" in cause && Array.isArray(cause.issues)) {
+    return cause.issues;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAutomationAgents",
-    kind: "query",
-    inputSchema: z.object({
-      ids: z.array(z.string().min(1)).min(1)
-    }),
-    cli: {
-      name: "get-automation-agents",
-      path: ["automations", "agents"],
-      description: "Fetch the agents attached to one or more automations.",
-      resultKey: "automationAgents",
-      options: [
-        stringArrayOption({
-          inputKey: "ids",
-          flagName: "ids",
-          description: "Automation IDs.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "automationAgents.graphql" },
-    document: `# Query automation agent relationships with flat agent fields only
-# Excludes nested agent config and schemas for MCP tool simplicity
-query GetAutomationAgents($ids: [ID!]!) {
-  automationAgents(ids: $ids) {
-    automationId
-    agentId
-    isTrigger
-    agent {
-      id
-      name
-      description
-      instructions
-      organizationId
-      createdAt
-      updatedAt
-      sourceAgentId
-      childAgentIds
-    }
+  if ("cause" in cause) {
+    return getZodIssuesFromCause(cause.cause, maxDepth - 1);
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAutomationRun",
-    kind: "query",
-    inputSchema: z.object({
-      id: z.string().min(1)
-    }),
-    cli: {
-      name: "get-automation-run",
-      path: ["automation-runs", "get"],
-      description: "Fetch a single automation run.",
-      resultKey: "automationRun",
-      options: [
-        stringOption({
-          inputKey: "id",
-          flagName: "id",
-          description: "Automation run ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "automationRun.graphql" },
-    document: `# Query a full automation run details payload
-query GetAutomationRun($id: ID!) {
-  automationRun(id: $id) {
-    id
-    automationId
-    parentAutomationRunId
-    status
-    statusDetail
-    summary
-    invocationType
-    input
-    additionalPrompt
-    debugUrl
-    createdAt
-    startedAt
-    pausedAt
-    finishedAt
+  return void 0;
+}
+function toUserFacingDetailsValue(value, depth) {
+  if (depth < 0) {
+    return void 0;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAutomationRunAgentRuns",
-    kind: "query",
-    inputSchema: z.object({
-      automationRunId: z.string().min(1)
-    }),
-    cli: {
-      name: "get-automation-run-agent-runs",
-      path: ["automation-runs", "agent-runs"],
-      description: "Fetch ordered agent runs for an automation run.",
-      resultKey: "automationRunAgentRuns",
-      options: [
-        stringOption({
-          inputKey: "automationRunId",
-          flagName: "automation-run-id",
-          description: "Automation run ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "automationRunAgentRuns.graphql" },
-    document: `# Query ordered agent runs for an automation run
-query GetAutomationRunAgentRuns($automationRunId: ID!) {
-  automationRunAgentRuns(automationRunId: $automationRunId) {
-    id
-    agentVersionId
-    agentName
-    status
-    statusDetail
-    isChildAgent
-    input
-    startedAt
-    finishedAt
-    parentAgentRunId
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAutomationRunIterations",
-    kind: "query",
-    inputSchema: z.object({
-      automationRunId: z.string().min(1),
-      agentRunId: z.string().min(1).optional(),
-      limit: z.number().int().positive().optional(),
-      reverse: z.boolean().optional()
-    }),
-    cli: {
-      name: "get-automation-run-iterations",
-      path: ["automation-runs", "iterations"],
-      description: "Fetch ordered iterations for an automation run.",
-      resultKey: "automationRunIterations",
-      options: [
-        stringOption({
-          inputKey: "automationRunId",
-          flagName: "automation-run-id",
-          description: "Automation run ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "agentRunId",
-          flagName: "agent-run-id",
-          description: "Optional agent run ID to filter by."
-        }),
-        numberOption({
-          inputKey: "limit",
-          flagName: "limit",
-          description: "Maximum number of iterations to return."
-        }),
-        booleanOption({
-          inputKey: "reverse",
-          flagName: "reverse",
-          description: "Return newest iterations first."
-        })
-      ]
-    },
-    mcp: { fileName: "automationRunIterations.graphql" },
-    document: `# Query iterations for an automation run with optional filtering by agent run
-query GetAutomationRunIterations(
-  $automationRunId: ID!
-  $agentRunId: ID
-  $limit: Int
-  $reverse: Boolean
-) {
-  automationRunIterations(
-    automationRunId: $automationRunId
-    agentRunId: $agentRunId
-    limit: $limit
-    reverse: $reverse
-  ) {
-    id
-    sequence
-    agentRunId
-    metadata
-    startedAt
-    finishedAt
-    totalDurationMs
-    llmResponseDurationMs
-    withMarksScreenshotUrl
-    withMarksMimeType
-    memories {
-      id
-      type
-      value
-      sequence
-      screenshotUrl
-      screenshotMimeType
+  if (Array.isArray(value)) {
+    const serializedValues = value.map((item) => toUserFacingDetailsValue(item, depth - 1)).filter((item) => item !== void 0);
+    return serializedValues;
+  }
+  if (value && typeof value === "object") {
+    const serializedObject = {};
+    for (const [key, itemValue] of Object.entries(value)) {
+      const serializedItemValue = toUserFacingDetailsValue(itemValue, depth - 1);
+      if (serializedItemValue !== void 0) {
+        serializedObject[key] = serializedItemValue;
+      }
+    }
+    if (Object.keys(serializedObject).length === 0) {
+      return void 0;
     }
+    return serializedObject;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAutomationRuns",
-    kind: "query",
-    inputSchema: z.object({
-      automationId: z.string().min(1),
-      status: z.array(z.string().min(1)).optional(),
-      invocationType: z.array(z.string().min(1)).optional(),
-      limit: z.number().int().positive().optional(),
-      page: z.number().int().positive().optional()
-    }),
-    cli: {
-      name: "get-automation-runs",
-      path: ["automation-runs", "list"],
-      description: "Fetch automation run history.",
-      resultKey: "automationRuns",
-      options: [
-        stringOption({
-          inputKey: "automationId",
-          flagName: "automation-id",
-          description: "Automation ID.",
-          required: true
-        }),
-        stringArrayOption({
-          inputKey: "status",
-          flagName: "status",
-          description: "Optional run statuses."
-        }),
-        stringArrayOption({
-          inputKey: "invocationType",
-          flagName: "invocation-type",
-          description: "Optional invocation types."
-        }),
-        numberOption({
-          inputKey: "limit",
-          flagName: "limit",
-          description: "Maximum number of runs to return."
-        }),
-        numberOption({
-          inputKey: "page",
-          flagName: "page",
-          description: "Page number."
-        })
-      ]
-    },
-    mcp: { fileName: "automationRuns.graphql" },
-    document: `# Query automation run history for a specific automation with optional filters
-query GetAutomationRuns(
-  $automationId: ID!
-  $status: [RunStatus!]
-  $invocationType: [InvocationType!]
-  $limit: Int
-  $page: Int
-) {
-  automationRuns(
-    automationId: $automationId
-    status: $status
-    invocationType: $invocationType
-    limit: $limit
-    page: $page
-  ) {
-    id
-    automationId
-    parentAutomationRunId
-    status
-    statusDetail
-    invocationType
-    summary
-    createdAt
-    startedAt
-    pausedAt
-    finishedAt
+  return void 0;
+}
+function resolveApiDetails({ appError, statusCode }) {
+  if (!shouldExposeMessage({ appError, statusCode })) {
+    return void 0;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "ListAutomations",
-    kind: "query",
-    inputSchema: z.object({
-      limit: z.number().positive().optional(),
-      order: jsonObjectSchema.optional(),
-      where: jsonObjectSchema.optional()
-    }),
-    cli: {
-      name: "list-automations",
-      path: ["automations", "list"],
-      description: "List automations with optional filters.",
-      resultKey: "automations",
-      options: [
-        numberOption({
-          inputKey: "limit",
-          flagName: "limit",
-          description: "Maximum number of automations to return."
-        }),
-        jsonOption({
-          inputKey: "order",
-          flagName: "order-json",
-          description: "GraphQL order object."
-        }),
-        jsonOption({
-          inputKey: "where",
-          flagName: "where-json",
-          description: "GraphQL filter object."
-        })
-      ]
-    },
-    mcp: { fileName: "listAutomations.graphql" },
-    document: `# Query to list automations with flat fields only (no nested objects)
-# Excludes config and agents for MCP tool simplicity
-query ListAutomations(
-  $limit: Float
-  $order: AutomationsOrder
-  $where: AutomationsWhereInput
-) {
-  automations(limit: $limit, order: $order, where: $where) {
-    id
-    name
-    organizationId
-    createdAt
-    updatedAt
-    environment
-    lastSavedAt
-    publishedVersionId
-    draftVersionId
+  const zodIssues = getZodIssuesFromCause(appError.cause);
+  if (zodIssues && zodIssues.length > 0) {
+    return {
+      validationErrors: zodIssues.map((issue) => ({
+        path: Array.isArray(issue.path) ? issue.path.map(String).join(".") : "",
+        message: typeof issue.message === "string" ? issue.message : "Invalid value",
+        ...typeof issue.code === "string" ? { code: issue.code } : {}
+      }))
+    };
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAutomations",
-    kind: "query",
-    inputSchema: z.object({
-      ids: z.array(z.string().min(1)).min(1)
-    }),
-    cli: {
-      name: "get-automations",
-      path: ["automations", "get"],
-      description: "Fetch one or more automations by IDs.",
-      resultKey: "automations",
-      options: [
-        stringArrayOption({
-          inputKey: "ids",
-          flagName: "ids",
-          description: "Automation IDs.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "automations.graphql" },
-    document: `# Query to fetch automations with flat fields only (no nested objects)
-# Excludes config and agents for MCP tool simplicity
-query GetAutomations($ids: [ID!]!) {
-  automations(ids: $ids) {
-    id
-    name
-    organizationId
-    createdAt
-    updatedAt
-    environment
-    lastSavedAt
-    publishedVersionId
-    draftVersionId
+  const rawDetails = toUserFacingDetailsValue(appError.details, 4);
+  if (rawDetails && typeof rawDetails === "object" && !Array.isArray(rawDetails) && Object.keys(rawDetails).length > 0) {
+    return rawDetails;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAvailableCommands",
-    kind: "query",
-    inputSchema: z.object({
-      env: z.string().min(1)
-    }),
-    cli: {
-      name: "get-available-commands",
-      path: ["catalog", "commands"],
-      description: "Fetch available command definitions by environment.",
-      resultKey: "availableCommands",
-      options: [
-        stringOption({
-          inputKey: "env",
-          flagName: "env",
-          description: "Environment name.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "availableCommands.graphql" },
-    document: `# Query to fetch available command definitions by environment
-query GetAvailableCommands($env: AvailableCommandsEnv!) {
-  availableCommands(env: $env) {
-    id
-    description
-    inputSchema
+  return void 0;
+}
+function getGraphQLErrorCodeFromAppErrorCode(code) {
+  if (code === 400) {
+    return "BAD_USER_INPUT";
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAvailableModels",
-    kind: "query",
-    inputSchema: z.object({
-      agentId: z.string().min(1)
-    }),
-    cli: {
-      name: "get-available-models",
-      path: ["catalog", "models"],
-      description: "Fetch available model definitions for an agent.",
-      resultKey: "availableModels",
-      options: [
-        stringOption({
-          inputKey: "agentId",
-          flagName: "agent-id",
-          description: "Agent ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "availableModels.graphql" },
-    document: `# Query to fetch available model definitions and pools for a specific agent
-query GetAvailableModels($agentId: String!) {
-  availableModels(agentId: $agentId) {
-    availableModelPools {
-      name
-      poolId
-      models {
-        id
-        name
-        description
-        status
-        provider
-      }
-    }
-    allAvailableModels {
-      id
-      name
-      description
-      status
-      provider
-    }
+  if (code === 401) {
+    return "UNAUTHORIZED";
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetAvailableTools",
-    kind: "query",
-    inputSchema: z.object({
-      env: z.string().min(1),
-      automationId: z.string().min(1).optional()
-    }),
-    cli: {
-      name: "get-available-tools",
-      path: ["catalog", "tools"],
-      description: "Fetch available tool definitions by environment.",
-      resultKey: "availableTools",
-      options: [
-        stringOption({
-          inputKey: "env",
-          flagName: "env",
-          description: "Environment name.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "automationId",
-          flagName: "automation-id",
-          description: "Optional automation ID."
-        })
-      ]
-    },
-    mcp: { fileName: "availableTools.graphql" },
-    document: `# Query to fetch available tool definitions by environment
-query GetAvailableTools($env: AvailableCommandsEnv!, $automationId: String) {
-  availableTools(env: $env, automationId: $automationId) {
-    id
-    description
-    inputSchema
+  if (code === 403) {
+    return "FORBIDDEN";
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "CreateAutomation",
-    kind: "mutation",
-    inputSchema: z.object({
-      input: jsonObjectSchema
-    }),
-    cli: {
-      name: "create-automation",
-      path: ["automations", "create"],
-      description: "Create a draft automation.",
-      resultKey: "createAutomation",
-      options: [
-        jsonOption({
-          inputKey: "input",
-          flagName: "input-json",
-          description: "CreateAutomationInput payload.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "createAutomation.graphql" },
-    document: `# Mutation to create a draft automation with optional initial values
-# Returns flat fields only for MCP tool simplicity
-mutation CreateAutomation($input: CreateAutomationInput!) {
-  createAutomation(input: $input) {
-    id
-    name
-    organizationId
-    createdAt
-    updatedAt
-    environment
-    lastSavedAt
-    publishedVersionId
-    draftVersionId
+  if (code === 404) {
+    return "NOT_FOUND";
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "GetGraphqlSchema",
-    kind: "query",
-    inputSchema: z.object({}),
-    cli: {
-      name: "get-graphql-schema",
-      path: ["graphql", "schema"],
-      description: "Fetch GraphQL schema metadata.",
-      resultKey: "graphqlSchema",
-      options: []
-    },
-    mcp: { fileName: "graphqlSchema.graphql" },
-    document: `# Query to fetch full GraphQL schema metadata.
-# Uses the first-class graphqlSchema query field to avoid __schema validation
-# issues in MCP tool-load paths while still returning introspection JSON.
-# Response can be large: call sparingly (typically once per task/session) and
-# reuse cached results.
-query GetGraphqlSchema {
-  graphqlSchema
-}`
-  }),
-  createOperationSpec({
-    operationName: "PauseAutomationRun",
-    kind: "mutation",
-    inputSchema: z.object({
-      automationRunId: z.string().min(1)
-    }),
-    cli: {
-      name: "pause-automation-run",
-      path: ["automation-runs", "pause"],
-      description: "Pause an automation run.",
-      resultKey: "pauseAutomationRun",
-      options: [
-        stringOption({
-          inputKey: "automationRunId",
-          flagName: "automation-run-id",
-          description: "Automation run ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "pauseAutomationRun.graphql" },
-    document: `# Mutation to pause an automation run
-mutation PauseAutomationRun($automationRunId: ID!) {
-  pauseAutomationRun(automationRunId: $automationRunId)
-}`
-  }),
-  createOperationSpec({
-    operationName: "RerunAutomation",
-    kind: "mutation",
-    inputSchema: z.object({
-      automationRunId: z.string().min(1),
-      additionalPrompt: z.string().min(1).optional(),
-      idempotencyKey: z.string().min(1)
-    }),
-    cli: {
-      name: "rerun-automation",
-      path: ["automation-runs", "rerun"],
-      description: "Rerun an existing automation run.",
-      resultKey: "rerunAutomation",
-      options: [
-        stringOption({
-          inputKey: "automationRunId",
-          flagName: "automation-run-id",
-          description: "Automation run ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "additionalPrompt",
-          flagName: "additional-prompt",
-          description: "Optional prompt appended to the rerun."
-        }),
-        stringOption({
-          inputKey: "idempotencyKey",
-          flagName: "idempotency-key",
-          description: "Idempotency key for the rerun request.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "rerunAutomation.graphql" },
-    document: `# Mutation to rerun an existing automation run
-mutation RerunAutomation(
-  $automationRunId: ID!
-  $additionalPrompt: String
-  $idempotencyKey: String!
-) {
-  rerunAutomation(
-    automationRunId: $automationRunId
-    additionalPrompt: $additionalPrompt
-    idempotencyKey: $idempotencyKey
-  ) {
-    automationRunId
-    workflowId
-    workflowRunId
+  if (code === 500) {
+    return "INTERNAL_SERVER_ERROR";
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "ResumeAutomationRun",
-    kind: "mutation",
-    inputSchema: z.object({
-      automationRunId: z.string().min(1),
-      message: z.string().min(1).optional()
-    }),
-    cli: {
-      name: "resume-automation-run",
-      path: ["automation-runs", "resume"],
-      description: "Resume a paused automation run.",
-      resultKey: "resumeAutomationRun",
-      options: [
-        stringOption({
-          inputKey: "automationRunId",
-          flagName: "automation-run-id",
-          description: "Automation run ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "message",
-          flagName: "message",
-          description: "Optional resume message."
-        })
-      ]
-    },
-    mcp: { fileName: "resumeAutomationRun.graphql" },
-    document: `# Mutation to resume an automation run
-mutation ResumeAutomationRun($automationRunId: ID!, $message: String) {
-  resumeAutomationRun(automationRunId: $automationRunId, message: $message)
-}`
-  }),
-  createOperationSpec({
-    operationName: "RunDraftAutomation",
-    kind: "mutation",
-    inputSchema: z.object({
-      draftAutomationId: z.string().min(1),
-      agentId: z.string().min(1),
-      idempotencyKey: z.string().min(1),
-      input: z.unknown().optional(),
-      additionalPrompt: z.string().min(1).optional()
-    }),
-    cli: {
-      name: "run-draft-automation",
-      path: ["automations", "run-draft"],
-      description: "Run a draft automation with an explicit trigger agent.",
-      resultKey: "runDraftAutomation",
-      options: [
-        stringOption({
-          inputKey: "draftAutomationId",
-          flagName: "draft-automation-id",
-          description: "Draft automation ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "agentId",
-          flagName: "agent-id",
-          description: "Trigger agent ID.",
-          required: true
-        }),
-        stringOption({
-          inputKey: "idempotencyKey",
-          flagName: "idempotency-key",
-          description: "Idempotency key for the run request.",
-          required: true
-        }),
-        jsonOption({
-          inputKey: "input",
-          flagName: "input-json",
-          description: "Optional JSON input payload."
-        }),
-        stringOption({
-          inputKey: "additionalPrompt",
-          flagName: "additional-prompt",
-          description: "Optional prompt appended to the run."
-        })
-      ]
-    },
-    mcp: { fileName: "runDraftAutomation.graphql" },
-    document: `# Mutation to run a draft automation with an explicit agent.
-# \`draftAutomationId\` is the draft automation entity ID (\`Automation.id\`), not \`draftVersionId\`.
-mutation RunDraftAutomation(
-  $draftAutomationId: ID!
-  $agentId: ID!
-  $idempotencyKey: String!
-  $input: JSON
-  $additionalPrompt: String
-) {
-  runDraftAutomation(
-    draftAutomationId: $draftAutomationId
-    agentId: $agentId
-    idempotencyKey: $idempotencyKey
-    input: $input
-    additionalPrompt: $additionalPrompt
-  ) {
-    automationRunId
-    workflowId
-    workflowRunId
+  return void 0;
+}
+function resolveGraphQLErrorCode(appError) {
+  const codeFromAppErrorCode = getGraphQLErrorCodeFromAppErrorCode(appError.statusCode);
+  if (codeFromAppErrorCode !== void 0) {
+    return codeFromAppErrorCode;
   }
-}`
-  }),
-  createOperationSpec({
-    operationName: "StopAutomationRun",
-    kind: "mutation",
-    inputSchema: z.object({
-      automationRunId: z.string().min(1)
-    }),
-    cli: {
-      name: "stop-automation-run",
-      path: ["automation-runs", "stop"],
-      description: "Stop an automation run.",
-      resultKey: "stopAutomationRun",
-      options: [
-        stringOption({
-          inputKey: "automationRunId",
-          flagName: "automation-run-id",
-          description: "Automation run ID.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "stopAutomationRun.graphql" },
-    document: `# Mutation to stop an automation run
-mutation StopAutomationRun($automationRunId: ID!) {
-  stopAutomationRun(automationRunId: $automationRunId)
-}`
-  }),
-  createOperationSpec({
-    operationName: "UpdateAutomationById",
-    kind: "mutation",
-    inputSchema: z.object({
-      id: z.string().min(1),
-      input: jsonObjectSchema
-    }),
-    cli: {
-      name: "update-automation-by-id",
-      path: ["automations", "update"],
-      description: "Update an automation.",
-      resultKey: "updateAutomation",
-      options: [
-        stringOption({
-          inputKey: "id",
-          flagName: "id",
-          description: "Automation ID.",
-          required: true
-        }),
-        jsonOption({
-          inputKey: "input",
-          flagName: "input-json",
-          description: "UpdateAutomationInput payload.",
-          required: true
-        })
-      ]
-    },
-    mcp: { fileName: "updateAutomation.graphql" },
-    document: `# Mutation to update an automation
-# Returns only id and lastSavedAt for MCP tool simplicity
-mutation UpdateAutomationById($id: ID!, $input: UpdateAutomationInput!) {
-  updateAutomation(id: $id, input: $input) {
-    id
-    lastSavedAt
+  const normalizedErrorType = appError.type.toLowerCase();
+  if (normalizedErrorType.includes("unauthorized")) {
+    return "UNAUTHORIZED";
   }
-}`
-  })
-];
-
-// src/program.ts
-import { Command as Command2, InvalidArgumentError as InvalidArgumentError2, Option as Option2 } from "commander";
+  if (normalizedErrorType.includes("forbidden")) {
+    return "FORBIDDEN";
+  }
+  if (normalizedErrorType.includes("not-found")) {
+    return "NOT_FOUND";
+  }
+  if (isCustomerUsageError(appError)) {
+    return "BAD_USER_INPUT";
+  }
+  return "INTERNAL_SERVER_ERROR";
+}
+function getStatusCodeFromGraphQLErrorCode(code) {
+  switch (code) {
+    case "BAD_USER_INPUT": {
+      return 400;
+    }
+    case "UNAUTHORIZED": {
+      return 401;
+    }
+    case "FORBIDDEN": {
+      return 403;
+    }
+    case "NOT_FOUND": {
+      return 404;
+    }
+    case "INTERNAL_SERVER_ERROR": {
+      return 500;
+    }
+  }
+}
+function getGraphQLErrorMessage({ code, apiMessage }) {
+  switch (code) {
+    case "BAD_USER_INPUT":
+    case "NOT_FOUND":
+    case "INTERNAL_SERVER_ERROR": {
+      return apiMessage;
+    }
+    case "UNAUTHORIZED": {
+      return "Unauthorized";
+    }
+    case "FORBIDDEN": {
+      return "Forbidden";
+    }
+  }
+}
+function getGraphQLAppErrorCode({ code, apiCode }) {
+  if (code === "INTERNAL_SERVER_ERROR" || code === "UNAUTHORIZED" || code === "FORBIDDEN") {
+    return code;
+  }
+  return apiCode;
+}
+function normalizeErrorCodeSegment(value) {
+  return value.trim().toUpperCase().replaceAll(/[^\dA-Z]+/gu, "_").replaceAll(/^_+/gu, "").replaceAll(/_+$/gu, "");
+}
+function getStatusCodeForAppErrorFromAppError(appError) {
+  const statusCodeFromCode = getStatusCodeFromAppErrorCode(appError.statusCode);
+  if (statusCodeFromCode !== void 0) {
+    return statusCodeFromCode;
+  }
+  if (isCustomerUsageError(appError)) {
+    return 400;
+  }
+  return 500;
+}
+function normalizeUserFacingErrorCode({ type, fallbackCode, prefix }) {
+  if (!type) {
+    return fallbackCode;
+  }
+  const normalized = normalizeErrorCodeSegment(type);
+  if (normalized.length === 0) {
+    return fallbackCode;
+  }
+  const normalizedPrefix = prefix ? normalizeErrorCodeSegment(prefix) : void 0;
+  if (!normalizedPrefix) {
+    return normalized;
+  }
+  if (normalized.startsWith(`${normalizedPrefix}_`)) {
+    return normalized;
+  }
+  return `${normalizedPrefix}_${normalized}`;
+}
+function toUserFacingApiErrorFromAppError({ appError, correlationId, statusCode }) {
+  const resolvedStatusCode = statusCode ?? getStatusCodeForAppErrorFromAppError(appError);
+  const message = resolveApiMessage({
+    appError,
+    statusCode: resolvedStatusCode
+  });
+  const suggestedAction = resolveSuggestedAction({
+    appError,
+    statusCode: resolvedStatusCode
+  });
+  const details = resolveApiDetails({
+    appError,
+    statusCode: resolvedStatusCode
+  });
+  return {
+    code: resolveApiErrorCode({
+      appError,
+      statusCode: resolvedStatusCode
+    }),
+    message,
+    correlationId,
+    suggestedAction,
+    ...details ? { details } : {}
+  };
+}
+function toUserFacingGraphQLErrorFromAppError({ appError, correlationId }) {
+  const code = resolveGraphQLErrorCode(appError);
+  const statusCode = getStatusCodeFromGraphQLErrorCode(code);
+  const apiError = toUserFacingApiErrorFromAppError({
+    appError,
+    correlationId,
+    statusCode
+  });
+  return {
+    code,
+    errorCode: getGraphQLAppErrorCode({ code, apiCode: apiError.code }),
+    message: getGraphQLErrorMessage({ code, apiMessage: apiError.message }),
+    correlationId
+  };
+}
 
-// src/api.ts
-import { z as z2 } from "zod";
-var workosOrganizationsResponseSchema = z2.object({
-  organizations: z2.array(
-    z2.object({
-      id: z2.string().min(1),
-      name: z2.string().min(1),
-      primaryDomain: z2.string().nullable().optional()
-    })
-  ),
-  success: z2.boolean()
-});
-var workosUserSchema = z2.object({
-  email: z2.string().nullable(),
-  id: z2.string().min(1)
-});
-var graphQlResponseSchema = z2.object({
-  data: z2.record(z2.string(), z2.unknown()).optional(),
-  errors: z2.array(
-    z2.object({
-      message: z2.string().min(1)
-    })
-  ).optional()
-});
-var apiErrorResponseSchema = z2.object({
-  errors: z2.array(
-    z2.object({
-      message: z2.string().min(1)
-    })
-  ).optional(),
-  message: z2.string().min(1).optional()
-});
-function getApiErrorDetail(responseBody) {
-  const parsedResponse = apiErrorResponseSchema.safeParse(responseBody);
-  if (!parsedResponse.success) {
-    return null;
-  }
-  if (parsedResponse.data.message) {
-    return parsedResponse.data.message;
-  }
-  if (!parsedResponse.data.errors || parsedResponse.data.errors.length === 0) {
-    return null;
-  }
-  return parsedResponse.data.errors.map((error) => error.message).join("\n");
+// ../common/dist/src/stdlib/error.js
+var INTERNAL_STACK_PATHS = [
+  "/src/stdlib/result.util.ts",
+  "/src/stdlib/error.ts"
+];
+function stripInternalFrames(stack, internalFrames) {
+  const lines = stack.split("\n");
+  return lines.filter((line) => !internalFrames.some((internalFrame) => line.includes(internalFrame)));
 }
-function trimTrailingSlash(value) {
-  return value.replace(/\/+$/u, "");
+var ORDERED_APP_ERROR_CATEGORIES = [
+  "internal_platform",
+  "customer_usage",
+  "third_party"
+];
+function isAppErrorCategory(category) {
+  return typeof category === "string" && // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  ORDERED_APP_ERROR_CATEGORIES.includes(category);
 }
-function createMagicalApiClient({
-  apiBaseUrl,
-  fetchFn = fetch
-}) {
-  const resolveApiBaseUrl = typeof apiBaseUrl === "string" ? () => apiBaseUrl : apiBaseUrl;
-  async function fetchJson({
-    accessToken,
-    path: path7,
-    init
-  }) {
-    const url = `${trimTrailingSlash(await resolveApiBaseUrl())}${path7}`;
-    const headers = new Headers(init?.headers);
-    headers.set("authorization", `Bearer ${accessToken}`);
-    const response = await fetchFn(url, {
-      ...init,
-      headers
-    }).catch((error) => {
-      throw new CliError(
-        `Failed to reach Magical API at ${url}. Check your configured base URL and make sure service-main is running.`,
-        { cause: error }
-      );
-    });
-    const responseBody = await response.json().catch((error) => {
-      if (!response.ok) {
-        throw new CliError(
-          `Magical API request to ${url} failed with status ${response.status}.`,
-          {
-            cause: error
-          }
-        );
-      }
-      throw new CliError(
-        `Magical API returned a non-JSON response for ${url}.`,
-        {
-          cause: error
-        }
-      );
-    });
-    if (!response.ok) {
-      const errorDetail = getApiErrorDetail(responseBody);
-      throw new CliError(
-        `Magical API request to ${url} failed with status ${response.status}${errorDetail ? `: ${errorDetail}` : "."}`
-      );
+function isNonEmptyAppErrorCategoryArray(categories) {
+  return Array.isArray(categories) && categories.length > 0 && categories.every(isAppErrorCategory);
+}
+var APP_ERROR_SEVERITIES = ["warn", "error", "fatal"];
+function isAppErrorCode(code) {
+  return typeof code === "number" && Number.isInteger(code) && code >= 400 && code <= 599;
+}
+function isAppErrorSeverity(severity) {
+  return typeof severity === "string" && // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  APP_ERROR_SEVERITIES.includes(severity);
+}
+var AppError = class _AppError extends Error {
+  type;
+  categories;
+  severity;
+  statusCode;
+  suggestedAction;
+  nonRetryable;
+  details;
+  constructor({ type, categories, severity, statusCode, code, message, suggestedAction, cause, nonRetryable, stack, internalFrames, ...details }) {
+    super(_AppError.resolveMessage(message, cause, type), { cause });
+    this.type = type;
+    this.name = type;
+    this.details = details;
+    this.categories = categories ?? _AppError.extractCategoriesFromCause(cause);
+    this.severity = severity ?? _AppError.extractSeverityFromCause(cause);
+    this.statusCode = statusCode ?? code ?? _AppError.extractStatusCodeFromCause(cause);
+    this.suggestedAction = suggestedAction ?? _AppError.extractSuggestedActionFromCause(cause);
+    this.nonRetryable = nonRetryable ?? false;
+    _AppError.applyStack(this, stack, internalFrames);
+  }
+  static resolveMessage(message, cause, type) {
+    if (message) {
+      return message;
     }
-    return responseBody;
+    if (cause instanceof Error) {
+      return cause.message;
+    }
+    return type;
   }
-  return {
-    async executeGraphQl({
-      accessToken,
-      query,
-      resultKey,
-      variables
-    }) {
-      const headers = new Headers();
-      headers.set("content-type", "application/json");
-      const parsedResponse = graphQlResponseSchema.safeParse(
-        await fetchJson({
-          accessToken,
-          path: "/graphql",
-          init: {
-            method: "POST",
-            headers,
-            body: JSON.stringify({
-              query,
-              variables
-            })
-          }
-        })
-      );
-      if (!parsedResponse.success) {
-        throw new CliError("GraphQL response payload was invalid.");
-      }
-      if (parsedResponse.data.errors && parsedResponse.data.errors.length > 0) {
-        throw new CliError(
-          parsedResponse.data.errors.map((error) => error.message).join("\n")
-        );
-      }
-      return parsedResponse.data.data?.[resultKey] ?? null;
-    },
-    async fetchOrganizations({ accessToken }) {
-      const parsedResponse = workosOrganizationsResponseSchema.safeParse(
-        await fetchJson({
-          accessToken,
-          path: "/workos/organizations"
-        })
-      );
-      if (!parsedResponse.success) {
-        throw new CliError("Organization list payload was invalid.");
+  static getInheritedCauseField(cause, extractor, seen = /* @__PURE__ */ new Set()) {
+    if (!cause || typeof cause !== "object" || seen.has(cause)) {
+      return void 0;
+    }
+    const causeRecord = cause;
+    const extractedValue = extractor(causeRecord);
+    if (extractedValue !== void 0) {
+      return extractedValue;
+    }
+    return _AppError.getInheritedCauseField(causeRecord["cause"], extractor, new Set(seen).add(cause));
+  }
+  static extractCategoriesFromCause(cause) {
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { categories } = causeRecord;
+      if (isNonEmptyAppErrorCategoryArray(categories)) {
+        return categories;
       }
-      return parsedResponse.data.organizations.map((organization) => ({
-        id: organization.id,
-        name: organization.name,
-        primaryDomain: organization.primaryDomain ?? null
-      }));
-    },
-    async fetchUser({
-      accessToken,
-      userId
-    }) {
-      const parsedResponse = workosUserSchema.safeParse(
-        await fetchJson({
-          accessToken,
-          path: `/workos/user/${userId}`
-        })
-      );
-      if (!parsedResponse.success) {
-        throw new CliError("User payload was invalid.");
+      return void 0;
+    }) ?? ["internal_platform"];
+  }
+  static extractSeverityFromCause(cause) {
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { severity } = causeRecord;
+      return isAppErrorSeverity(severity) ? severity : void 0;
+    }) ?? "error";
+  }
+  static extractStatusCodeFromCause(cause) {
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { statusCode } = causeRecord;
+      if (isAppErrorCode(statusCode)) {
+        return statusCode;
       }
-      return parsedResponse.data;
-    }
-  };
-}
-
-// src/config.ts
-import os from "os";
-import path from "path";
-var DEFAULT_MAGICAL_API_URL = "https://api-agt.getmagical.io";
-var DEFAULT_WORKOS_API_URL = "https://api.workos.com";
-var DEFAULT_WORKOS_CLIENT_ID = "client_01JJZ6XJ1RF248P20WF63M4VAM";
-var DEFAULT_STAGING_WORKOS_CLIENT_ID = "client_01JJZ6X26BGFBT8AC303XPQ9EQ";
-var DEFAULT_KEYCHAIN_SERVICE_NAME = "@getmagical/mcp-cli";
-var DEFAULT_CLI_DIST_TAG = "latest";
-var DEFAULT_CLI_NPM_REGISTRY_URL = "https://registry.npmjs.org/";
-var CLI_CONFIG_DIRECTORY_NAME = "magical-mcp-cli";
-var CLI_ACCESS_TOKEN_FILE_NAME = "access-token.txt";
-var CLI_STATE_FILE_NAME = "state.json";
-var CLI_SETTINGS_FILE_NAME = "settings.json";
-var CLI_REFRESH_TOKEN_FILE_NAME = "refresh-tokens.json";
-function resolvePlatformConfigDirectory() {
-  const customConfigDirectory = process.env["MAGICAL_CLI_CONFIG_DIR"];
-  if (customConfigDirectory) {
-    return customConfigDirectory;
+      const { code: legacyCode } = causeRecord;
+      return isAppErrorCode(legacyCode) ? legacyCode : void 0;
+    });
+  }
+  /** @deprecated Use statusCode instead. */
+  get code() {
+    return this.statusCode;
   }
-  if (process.platform === "darwin") {
-    return path.join(os.homedir(), "Library", "Application Support");
+  static extractSuggestedActionFromCause(cause) {
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { suggestedAction } = causeRecord;
+      if (typeof suggestedAction !== "string") {
+        return void 0;
+      }
+      const trimmedSuggestedAction = suggestedAction.trim();
+      return trimmedSuggestedAction.length > 0 ? trimmedSuggestedAction : void 0;
+    });
   }
-  if (process.platform === "win32") {
-    const appDataDirectory = process.env["APPDATA"];
-    return appDataDirectory ?? path.join(os.homedir(), "AppData", "Roaming");
+  static applyStack(error, stack, internalFrames) {
+    if (stack) {
+      error.stack = stack;
+    }
+    error.stack &&= stripInternalFrames(error.stack, [
+      ...INTERNAL_STACK_PATHS,
+      ...internalFrames ?? []
+    ]).join("\n");
   }
-  return process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config");
+  toApiError({ correlationId }) {
+    return toUserFacingApiError({
+      error: this,
+      correlationId,
+      statusCode: getStatusCodeForAppError(this)
+    });
+  }
+  toGqlError({ correlationId }) {
+    return toUserFacingGraphQLError({
+      error: this,
+      correlationId
+    });
+  }
+};
+function toAppError(error) {
+  return error instanceof AppError ? error : new AppError(error);
 }
-function resolveRefreshTokenStoreKind() {
-  return process.env["MAGICAL_CLI_REFRESH_TOKEN_STORE"] === "file" ? "file" : "keytar";
+function getStatusCodeForAppError(error) {
+  const appError = toAppError(error);
+  return getStatusCodeForAppErrorFromAppError(appError);
 }
-function getRuntimeConfig() {
-  const configDirectory = path.join(
-    resolvePlatformConfigDirectory(),
-    CLI_CONFIG_DIRECTORY_NAME
-  );
-  return {
-    accessTokenFilePath: path.join(configDirectory, CLI_ACCESS_TOKEN_FILE_NAME),
-    cliDistTag: process.env["MAGICAL_CLI_DIST_TAG"] ?? DEFAULT_CLI_DIST_TAG,
-    magicalApiUrl: DEFAULT_MAGICAL_API_URL,
-    npmRegistryUrl: process.env["MAGICAL_CLI_NPM_REGISTRY_URL"] ?? DEFAULT_CLI_NPM_REGISTRY_URL,
-    refreshTokenFilePath: path.join(
-      configDirectory,
-      CLI_REFRESH_TOKEN_FILE_NAME
-    ),
-    refreshTokenStoreKind: resolveRefreshTokenStoreKind(),
-    stateFilePath: path.join(configDirectory, CLI_STATE_FILE_NAME),
-    workosApiUrl: DEFAULT_WORKOS_API_URL,
-    workosClientId: DEFAULT_WORKOS_CLIENT_ID,
-    keychainServiceName: DEFAULT_KEYCHAIN_SERVICE_NAME
-  };
+function toUserFacingApiError({ error, correlationId, statusCode }) {
+  const appError = toAppError(error);
+  return toUserFacingApiErrorFromAppError({
+    appError,
+    correlationId,
+    statusCode
+  });
 }
-function requireWorkosClientId(config) {
-  return config.workosClientId;
+function toUserFacingGraphQLError({ error, correlationId }) {
+  const appError = toAppError(error);
+  return toUserFacingGraphQLErrorFromAppError({
+    appError,
+    correlationId
+  });
 }
 
-// src/settings.ts
-import { mkdir, readFile, rm, writeFile } from "fs/promises";
-import path2 from "path";
-
-// ../common/dist/src/stdlib/json.util.js
-var import_ts_essentials = __toESM(require_dist(), 1);
-
 // ../common/dist/src/stdlib/result.util.js
-import { z as z3 } from "zod";
-
-// ../common/dist/src/stdlib/error-user-facing.js
-var USER_FACING_STATUS_MESSAGES = /* @__PURE__ */ new Map([
-  [400, "Bad Request"],
-  [401, "Unauthorized"],
-  [403, "Forbidden"],
-  [404, "Not Found"],
-  [500, "Internal Server Error"],
-  [503, "Service Unavailable"]
-]);
-var USER_FACING_DEFAULT_ACTIONS = /* @__PURE__ */ new Map([
-  [400, "Review the request payload and retry."],
-  [401, "Authenticate and retry the request."],
-  [403, "Verify your permissions and retry the request."],
-  [404, "Verify the requested resource exists and retry."],
-  [
-    500,
-    "Retry the request. If this keeps happening, contact support and share the correlation ID."
-  ],
-  [
-    503,
-    "Retry the request after a brief delay. If this keeps happening, contact support and share the correlation ID."
-  ]
-]);
-var USER_FACING_FALLBACK_CODES = /* @__PURE__ */ new Map([
-  [400, "BAD_REQUEST"],
-  [401, "UNAUTHORIZED"],
-  [403, "FORBIDDEN"],
-  [404, "NOT_FOUND"],
-  [500, "INTERNAL_SERVER_ERROR"],
-  [503, "SERVICE_UNAVAILABLE"]
-]);
-function isCustomerUsageError(appError) {
-  return appError.categories.includes("customer_usage");
-}
-function getStatusCodeFromAppErrorCode(code) {
-  if (typeof code !== "number" || !Number.isInteger(code)) {
-    return void 0;
+var Result;
+(function(Result2) {
+  function partition(responses) {
+    const oks = responses.filter((resp) => resp._tag === "Ok").map((resp) => resp.value);
+    const errs = responses.filter((resp) => resp._tag === "Err").map((resp) => resp.error);
+    return [oks, errs];
   }
-  if (code >= 400 && code <= 599) {
-    return code;
+  Result2.partition = partition;
+  async function promiseAllAndPartition(promises) {
+    const results = await Promise.all(promises);
+    return partition(results);
   }
-  return void 0;
-}
-function getStatusFamilyFallbackCode(statusCode) {
-  if (statusCode >= 400 && statusCode <= 499) {
-    return 400;
+  Result2.promiseAllAndPartition = promiseAllAndPartition;
+  function unwrapOrThrow(result) {
+    if (isErr(result)) {
+      throw result.error;
+    }
+    return result.value;
   }
-  return 500;
-}
-function getStatusMessage(statusCode) {
-  const directMessage = USER_FACING_STATUS_MESSAGES.get(statusCode);
-  if (directMessage !== void 0) {
-    return directMessage;
+  Result2.unwrapOrThrow = unwrapOrThrow;
+  async function all(promises) {
+    const results = await fromThrowable(async () => Promise.all(promises.map(async (promise) => {
+      const result = await promise;
+      if (isErr(result)) {
+        throw result.error;
+      }
+      return result;
+    })), "unknown-error");
+    if (isErr(results)) {
+      return ErrFromThrowable(results.error.cause);
+    }
+    return Ok(results.value.map((r) => r.value));
   }
-  return getStatusFamilyFallbackCode(statusCode) === 400 ? "Bad Request" : "Internal Server Error";
+  Result2.all = all;
+  function andThenSync(fnFirst, ...fns) {
+    let result = fnFirst();
+    const values = [];
+    for (const fn of fns) {
+      if (isErr(result)) {
+        return result;
+      }
+      values.unshift(result.value);
+      result = fn(...values);
+    }
+    return result;
+  }
+  Result2.andThenSync = andThenSync;
+  async function andThen(fnFirst, ...fns) {
+    let result = await fnFirst();
+    const values = [];
+    for (const fn of fns) {
+      if (isErr(result)) {
+        return result;
+      }
+      values.unshift(result.value);
+      result = await fn(...values);
+    }
+    return result;
+  }
+  Result2.andThen = andThen;
+})(Result || (Result = {}));
+function Ok(value) {
+  if (arguments.length === 0) {
+    return {
+      _tag: "Ok",
+      value: void 0
+    };
+  }
+  return {
+    _tag: "Ok",
+    value
+  };
 }
-function getDefaultSuggestedAction(statusCode) {
-  const directAction = USER_FACING_DEFAULT_ACTIONS.get(statusCode);
-  if (directAction !== void 0) {
-    return directAction;
+function Err(error) {
+  return {
+    _tag: "Err",
+    error: new AppError(error)
+  };
+}
+function ErrFromThrowable(error) {
+  return {
+    _tag: "Err",
+    error
+  };
+}
+function isErr(result) {
+  return result._tag === "Err";
+}
+function fromThrowable(fn, errorType, errorInfo) {
+  try {
+    const result = fn();
+    if (result && typeof result.then === "function") {
+      return result.then((value) => Ok(value)).catch((err) => Err({
+        ...errorInfo,
+        type: errorType,
+        cause: err
+      }));
+    }
+    return Ok(result);
+  } catch (err) {
+    return Err({
+      ...errorInfo,
+      type: errorType,
+      cause: err
+    });
   }
-  return getStatusFamilyFallbackCode(statusCode) === 400 ? "Review the request payload and retry." : "Retry the request. If this keeps happening, contact support and share the correlation ID.";
 }
-function getFallbackErrorCode(statusCode) {
-  const directCode = USER_FACING_FALLBACK_CODES.get(statusCode);
-  if (directCode !== void 0) {
-    return directCode;
+
+// ../common/dist/src/stdlib/json.util.js
+function safeJsonParse(json) {
+  try {
+    return Ok(JSON.parse(json));
+  } catch (error) {
+    console.warn("Failed to parse JSON", { error, json });
+    return Err({ type: "invalid-json", cause: error, json });
   }
-  return getStatusFamilyFallbackCode(statusCode) === 400 ? "BAD_REQUEST" : "INTERNAL_SERVER_ERROR";
 }
-function shouldExposeMessage({ appError, statusCode }) {
-  if (statusCode >= 500) {
-    return false;
-  }
-  return isCustomerUsageError(appError);
+
+// ../mcp-registry/src/operation-specs.ts
+import { z as z2 } from "zod";
+
+// ../mcp-registry/src/operation-spec.ts
+function stripLeadingGraphqlComments(document) {
+  return document.replace(/^(?:\s*#.*\n)+/u, "").trimStart();
 }
-function resolveApiMessage({ appError, statusCode }) {
-  if (!shouldExposeMessage({ appError, statusCode })) {
-    return getStatusMessage(statusCode);
+function assertDocumentMatchesOperation({
+  document,
+  kind,
+  operationName
+}) {
+  const normalizedDocument = stripLeadingGraphqlComments(document);
+  const match = /^(?<actualKind>query|mutation)\s+(?<actualOperationName>[_A-Za-z][_0-9A-Za-z]*)/u.exec(
+    normalizedDocument
+  );
+  const actualKind = match?.groups?.["actualKind"];
+  const actualOperationName = match?.groups?.["actualOperationName"];
+  if (!actualKind || !actualOperationName) {
+    throw new Error(
+      `Operation "${operationName}" is missing a top-level GraphQL ${kind} definition.`
+    );
   }
-  const trimmedMessage = appError.message.trim();
-  if (trimmedMessage.length > 0) {
-    return trimmedMessage;
+  if (actualKind !== kind || actualOperationName !== operationName) {
+    throw new Error(
+      `Operation "${operationName}" does not match its GraphQL document (${actualKind} ${actualOperationName}).`
+    );
   }
-  return getStatusMessage(statusCode);
 }
-function resolveApiErrorCode({ appError, statusCode }) {
-  if (!shouldExposeMessage({ appError, statusCode })) {
-    return getFallbackErrorCode(statusCode);
-  }
-  return normalizeUserFacingErrorCode({
-    type: appError.type,
-    fallbackCode: getFallbackErrorCode(statusCode)
-  });
+function createOperationSpec(spec) {
+  assertDocumentMatchesOperation(spec);
+  return spec;
 }
-function resolveSuggestedAction({ appError, statusCode }) {
-  const trimmedSuggestedAction = appError.suggestedAction?.trim();
-  if (shouldExposeMessage({ appError, statusCode }) && trimmedSuggestedAction) {
-    return trimmedSuggestedAction;
-  }
-  return getDefaultSuggestedAction(statusCode);
+
+// ../mcp-registry/src/operation-specs.ts
+function stringOption({
+  description,
+  flagName,
+  inputKey,
+  required = false
+}) {
+  return {
+    description,
+    flagName,
+    inputKey,
+    required,
+    valueType: "string"
+  };
 }
-function getZodIssuesFromCause(cause, maxDepth = 10) {
-  if (maxDepth < 0 || typeof cause !== "object" || cause === null) {
-    return void 0;
-  }
-  if ("issues" in cause && Array.isArray(cause.issues)) {
-    return cause.issues;
-  }
-  if ("cause" in cause) {
-    return getZodIssuesFromCause(cause.cause, maxDepth - 1);
-  }
-  return void 0;
+function numberOption({
+  description,
+  flagName,
+  inputKey,
+  required = false
+}) {
+  return {
+    description,
+    flagName,
+    inputKey,
+    required,
+    valueType: "number"
+  };
 }
-function toUserFacingDetailsValue(value, depth) {
-  if (depth < 0) {
-    return void 0;
-  }
-  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    const serializedValues = value.map((item) => toUserFacingDetailsValue(item, depth - 1)).filter((item) => item !== void 0);
-    return serializedValues;
-  }
-  if (value && typeof value === "object") {
-    const serializedObject = {};
-    for (const [key, itemValue] of Object.entries(value)) {
-      const serializedItemValue = toUserFacingDetailsValue(itemValue, depth - 1);
-      if (serializedItemValue !== void 0) {
-        serializedObject[key] = serializedItemValue;
-      }
+function booleanOption({
+  description,
+  flagName,
+  inputKey
+}) {
+  return {
+    description,
+    flagName,
+    inputKey,
+    valueType: "boolean"
+  };
+}
+function stringArrayOption({
+  description,
+  flagName,
+  inputKey,
+  required = false
+}) {
+  return {
+    description,
+    flagName,
+    inputKey,
+    required,
+    valueHint: "comma-separated",
+    valueType: "string-array"
+  };
+}
+function jsonOption({
+  description,
+  flagName,
+  inputKey,
+  required = false
+}) {
+  return {
+    description,
+    flagName,
+    inputKey,
+    required,
+    valueHint: "JSON",
+    valueType: "json"
+  };
+}
+var jsonObjectSchema = z2.record(z2.string(), z2.unknown());
+var agentBrowserProviderOptionsSelection = `            browserbase {
+              advancedStealth
+              contextId
+              extensionId
+              instanceSize
+              blockAds
+              solveCaptchas
+              viewport {
+                width
+                height
+              }
+            }
+            agentCore {
+              viewport {
+                width
+                height
+              }
+              enableWebBotAuth
+            }
+            local {
+              viewport {
+                width
+                height
+              }
+            }
+            hyperbrowser {
+              viewport {
+                width
+                height
+              }
+            }
+            steel {
+              extensionIds
+              region
+              solveCaptcha
+              viewport {
+                width
+                height
+              }
+            }`;
+var agentEnvironmentOptionsSelection = `      environmentOptions {
+        __typename
+        ... on AgentConfig_environmentOptions_Browser {
+          environment
+          maxMediaToIncludeInMemory
+          saveAuthCookiesAfterRun
+          startingUrl
+          browserProvider
+          browserProviderOptions {
+${agentBrowserProviderOptionsSelection}
+          }
+        }
+        ... on AgentConfig_environmentOptions_Browsercoordinates {
+          environment
+          maxMediaToIncludeInMemory
+          saveAuthCookiesAfterRun
+          startingUrl
+          browserProvider
+          browserProviderOptions {
+${agentBrowserProviderOptionsSelection}
+          }
+        }
+        ... on AgentConfig_environmentOptions_Desktop {
+          environment
+          browserProvider
+          browserProviderOptions {
+${agentBrowserProviderOptionsSelection}
+          }
+          maxMediaToIncludeInMemory
+          startingUrl
+          useCopyPasteForTyping
+        }
+        ... on AgentConfig_environmentOptions_Desktopapp {
+          environment
+          maxMediaToIncludeInMemory
+        }
+        ... on AgentConfig_environmentOptions_Minimal {
+          environment
+        }
+      }`;
+var agentLimitationsSelection = `      limitations {
+        maxDurationSeconds
+        maxToolCalls
+        allowedUrlRegexes
+      }`;
+var operationSpecs = [
+  createOperationSpec({
+    operationName: "GetAgents",
+    kind: "query",
+    inputSchema: z2.object({
+      ids: z2.array(z2.string().min(1)).min(1)
+    }),
+    cli: {
+      name: "get-agents",
+      path: ["agents", "get"],
+      description: "Fetch one or more agents with config and schema fields.",
+      resultKey: "agents",
+      options: [
+        stringArrayOption({
+          inputKey: "ids",
+          flagName: "ids",
+          description: "Agent IDs.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "agents.graphql" },
+    document: `# Query to fetch multiple agents with all fields
+# Includes nested environment and limitation config fields
+query GetAgents($ids: [ID!]!) {
+  agents(ids: $ids) {
+    id
+    name
+    description
+    instructions
+    organizationId
+    createdAt
+    updatedAt
+    sourceAgentId
+    inputSchema
+    outputSchema
+    config {
+      type
+      language
+      model
+      tools
+      maxSessionMessages
+${agentEnvironmentOptionsSelection}
+${agentLimitationsSelection}
+      commonParametersSchema
+      taskQueue
+      waitUponQueueing
+      queueableAgentIds
+      systemPrompt
+      additionalSystemPrompt
+      ignoreUnstableSessionState
     }
-    if (Object.keys(serializedObject).length === 0) {
-      return void 0;
+    childAgentIds
     }
-    return serializedObject;
-  }
-  return void 0;
-}
-function resolveApiDetails({ appError, statusCode }) {
-  if (!shouldExposeMessage({ appError, statusCode })) {
-    return void 0;
-  }
-  const zodIssues = getZodIssuesFromCause(appError.cause);
-  if (zodIssues && zodIssues.length > 0) {
-    return {
-      validationErrors: zodIssues.map((issue) => ({
-        path: Array.isArray(issue.path) ? issue.path.map(String).join(".") : "",
-        message: typeof issue.message === "string" ? issue.message : "Invalid value",
-        ...typeof issue.code === "string" ? { code: issue.code } : {}
-      }))
-    };
-  }
-  const rawDetails = toUserFacingDetailsValue(appError.details, 4);
-  if (rawDetails && typeof rawDetails === "object" && !Array.isArray(rawDetails) && Object.keys(rawDetails).length > 0) {
-    return rawDetails;
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAgentVersion",
+    kind: "query",
+    inputSchema: z2.object({
+      agentId: z2.string().min(1),
+      versionId: z2.string().min(1)
+    }),
+    cli: {
+      name: "get-agent-version",
+      path: ["agents", "versions", "get"],
+      description: "Fetch one saved version for an agent.",
+      resultKey: "agentVersion",
+      options: [
+        stringOption({
+          inputKey: "agentId",
+          flagName: "agent-id",
+          description: "Agent ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "versionId",
+          flagName: "version-id",
+          description: "Agent version ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "agentVersion.graphql" },
+    document: `# Query to fetch a specific saved version for an agent
+query GetAgentVersion($agentId: ID!, $versionId: ID!) {
+  agentVersion(agentId: $agentId, versionId: $versionId) {
+    id
+    agentId
+    sequence
+    name
+    description
+    instructions
+    instructionsMode
+    instructionsDoc
+    updaterUserId
+    createdAt
+    updatedAt
+    inputSchema
+    outputSchema
+    config {
+      type
+      language
+      model
+      tools
+      maxSessionMessages
+${agentEnvironmentOptionsSelection}
+${agentLimitationsSelection}
+      commonParametersSchema
+      taskQueue
+      waitUponQueueing
+      queueableAgentIds
+      systemPrompt
+      additionalSystemPrompt
+      ignoreUnstableSessionState
+    }
+    isCurrent
   }
-  return void 0;
-}
-function getGraphQLErrorCodeFromAppErrorCode(code) {
-  if (code === 400) {
-    return "BAD_USER_INPUT";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAgentVersions",
+    kind: "query",
+    inputSchema: z2.object({
+      agentId: z2.string().min(1)
+    }),
+    cli: {
+      name: "get-agent-versions",
+      path: ["agents", "versions", "list"],
+      description: "Fetch version history for an agent.",
+      resultKey: "agentVersions",
+      options: [
+        stringOption({
+          inputKey: "agentId",
+          flagName: "agent-id",
+          description: "Agent ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "agentVersions.graphql" },
+    document: `# Query to fetch version history metadata for an agent
+query GetAgentVersions($agentId: ID!) {
+  agentVersions(agentId: $agentId) {
+    id
+    sequence
+    name
+    description
+    updaterUserId
+    createdAt
+    updatedAt
+    isCurrent
   }
-  if (code === 401) {
-    return "UNAUTHORIZED";
+}`
+  }),
+  createOperationSpec({
+    operationName: "DiffAgentVersion",
+    kind: "query",
+    inputSchema: z2.object({
+      agentId: z2.string().min(1),
+      versionId: z2.string().min(1),
+      compareVersionId: z2.string().min(1).optional()
+    }),
+    cli: {
+      name: "diff-agent-version",
+      path: ["agents", "versions", "diff"],
+      description: "Diff one agent version against another version or the current latest version.",
+      resultKey: "agentVersionDiff",
+      options: [
+        stringOption({
+          inputKey: "agentId",
+          flagName: "agent-id",
+          description: "Agent ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "versionId",
+          flagName: "version-id",
+          description: "Source agent version ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "compareVersionId",
+          flagName: "compare-version-id",
+          description: "Optional target version ID. Defaults to the current latest version."
+        })
+      ]
+    },
+    mcp: { fileName: "agentVersionDiff.graphql" },
+    document: `# Query to diff one agent version against another or the current latest version
+query DiffAgentVersion(
+  $agentId: ID!
+  $versionId: ID!
+  $compareVersionId: ID
+) {
+  agentVersionDiff(
+    agentId: $agentId
+    versionId: $versionId
+    compareVersionId: $compareVersionId
+  ) {
+    agentId
+    fromVersionId
+    toVersionId
+    hasChanges
+    changes {
+      field
+      oldValue
+      newValue
+    }
   }
-  if (code === 403) {
-    return "FORBIDDEN";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAgentRun",
+    kind: "query",
+    inputSchema: z2.object({
+      id: z2.string().min(1)
+    }),
+    cli: {
+      name: "get-agent-run",
+      path: ["agent-runs", "get"],
+      description: "Fetch a single agent run.",
+      resultKey: "agentRun",
+      options: [
+        stringOption({
+          inputKey: "id",
+          flagName: "id",
+          description: "Agent run ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "agentRun.graphql" },
+    document: `# Query a single agent run
+query GetAgentRun($id: ID!) {
+  agentRun(id: $id) {
+    id
+    agentVersionId
+    agentName
+    status
+    statusDetail
+    isChildAgent
+    input
+    startedAt
+    finishedAt
+    parentAgentRunId
   }
-  if (code === 404) {
-    return "NOT_FOUND";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomationAgents",
+    kind: "query",
+    inputSchema: z2.object({
+      ids: z2.array(z2.string().min(1)).min(1)
+    }),
+    cli: {
+      name: "get-automation-agents",
+      path: ["automations", "agents"],
+      description: "Fetch the agents attached to one or more automations.",
+      resultKey: "automationAgents",
+      options: [
+        stringArrayOption({
+          inputKey: "ids",
+          flagName: "ids",
+          description: "Automation IDs.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "automationAgents.graphql" },
+    document: `# Query automation agent relationships with flat agent fields only
+# Excludes nested agent config and schemas for MCP tool simplicity
+query GetAutomationAgents($ids: [ID!]!) {
+  automationAgents(ids: $ids) {
+    automationId
+    agentId
+    isTrigger
+    agent {
+      id
+      name
+      description
+      instructions
+      organizationId
+      createdAt
+      updatedAt
+      sourceAgentId
+      childAgentIds
+    }
   }
-  if (code === 500) {
-    return "INTERNAL_SERVER_ERROR";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomationRun",
+    kind: "query",
+    inputSchema: z2.object({
+      id: z2.string().min(1)
+    }),
+    cli: {
+      name: "get-automation-run",
+      path: ["automation-runs", "get"],
+      description: "Fetch a single automation run.",
+      resultKey: "automationRun",
+      options: [
+        stringOption({
+          inputKey: "id",
+          flagName: "id",
+          description: "Automation run ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "automationRun.graphql" },
+    document: `# Query a full automation run details payload
+query GetAutomationRun($id: ID!) {
+  automationRun(id: $id) {
+    id
+    automationId
+    parentAutomationRunId
+    status
+    statusDetail
+    summary
+    invocationType
+    input
+    additionalPrompt
+    debugUrl
+    createdAt
+    startedAt
+    pausedAt
+    finishedAt
   }
-  return void 0;
-}
-function resolveGraphQLErrorCode(appError) {
-  const codeFromAppErrorCode = getGraphQLErrorCodeFromAppErrorCode(appError.statusCode);
-  if (codeFromAppErrorCode !== void 0) {
-    return codeFromAppErrorCode;
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomationRunAgentRuns",
+    kind: "query",
+    inputSchema: z2.object({
+      automationRunId: z2.string().min(1)
+    }),
+    cli: {
+      name: "get-automation-run-agent-runs",
+      path: ["automation-runs", "agent-runs"],
+      description: "Fetch ordered agent runs for an automation run.",
+      resultKey: "automationRunAgentRuns",
+      options: [
+        stringOption({
+          inputKey: "automationRunId",
+          flagName: "automation-run-id",
+          description: "Automation run ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "automationRunAgentRuns.graphql" },
+    document: `# Query ordered agent runs for an automation run
+query GetAutomationRunAgentRuns($automationRunId: ID!) {
+  automationRunAgentRuns(automationRunId: $automationRunId) {
+    id
+    agentVersionId
+    agentName
+    status
+    statusDetail
+    isChildAgent
+    input
+    startedAt
+    finishedAt
+    parentAgentRunId
   }
-  const normalizedErrorType = appError.type.toLowerCase();
-  if (normalizedErrorType.includes("unauthorized")) {
-    return "UNAUTHORIZED";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomationRunIterations",
+    kind: "query",
+    inputSchema: z2.object({
+      automationRunId: z2.string().min(1),
+      agentRunId: z2.string().min(1).optional(),
+      limit: z2.number().int().positive().optional(),
+      reverse: z2.boolean().optional()
+    }),
+    cli: {
+      name: "get-automation-run-iterations",
+      path: ["automation-runs", "iterations"],
+      description: "Fetch ordered iterations for an automation run.",
+      resultKey: "automationRunIterations",
+      options: [
+        stringOption({
+          inputKey: "automationRunId",
+          flagName: "automation-run-id",
+          description: "Automation run ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "agentRunId",
+          flagName: "agent-run-id",
+          description: "Optional agent run ID to filter by."
+        }),
+        numberOption({
+          inputKey: "limit",
+          flagName: "limit",
+          description: "Maximum number of iterations to return."
+        }),
+        booleanOption({
+          inputKey: "reverse",
+          flagName: "reverse",
+          description: "Return newest iterations first."
+        })
+      ]
+    },
+    mcp: { fileName: "automationRunIterations.graphql" },
+    document: `# Query iterations for an automation run with optional filtering by agent run
+query GetAutomationRunIterations(
+  $automationRunId: ID!
+  $agentRunId: ID
+  $limit: Int
+  $reverse: Boolean
+) {
+  automationRunIterations(
+    automationRunId: $automationRunId
+    agentRunId: $agentRunId
+    limit: $limit
+    reverse: $reverse
+  ) {
+    id
+    sequence
+    agentRunId
+    metadata
+    startedAt
+    finishedAt
+    totalDurationMs
+    llmResponseDurationMs
+    withMarksScreenshotUrl
+    withMarksMimeType
+    memories {
+      id
+      type
+      value
+      sequence
+      screenshotUrl
+      screenshotMimeType
+    }
   }
-  if (normalizedErrorType.includes("forbidden")) {
-    return "FORBIDDEN";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomationRuns",
+    kind: "query",
+    inputSchema: z2.object({
+      automationId: z2.string().min(1),
+      status: z2.array(z2.string().min(1)).optional(),
+      invocationType: z2.array(z2.string().min(1)).optional(),
+      limit: z2.number().int().positive().optional(),
+      page: z2.number().int().positive().optional()
+    }),
+    cli: {
+      name: "get-automation-runs",
+      path: ["automation-runs", "list"],
+      description: "Fetch automation run history.",
+      resultKey: "automationRuns",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        }),
+        stringArrayOption({
+          inputKey: "status",
+          flagName: "status",
+          description: "Optional run statuses."
+        }),
+        stringArrayOption({
+          inputKey: "invocationType",
+          flagName: "invocation-type",
+          description: "Optional invocation types."
+        }),
+        numberOption({
+          inputKey: "limit",
+          flagName: "limit",
+          description: "Maximum number of runs to return."
+        }),
+        numberOption({
+          inputKey: "page",
+          flagName: "page",
+          description: "Page number."
+        })
+      ]
+    },
+    mcp: { fileName: "automationRuns.graphql" },
+    document: `# Query automation run history for a specific automation with optional filters
+query GetAutomationRuns(
+  $automationId: ID!
+  $status: [RunStatus!]
+  $invocationType: [InvocationType!]
+  $limit: Int
+  $page: Int
+) {
+  automationRuns(
+    automationId: $automationId
+    status: $status
+    invocationType: $invocationType
+    limit: $limit
+    page: $page
+  ) {
+    id
+    automationId
+    parentAutomationRunId
+    status
+    statusDetail
+    invocationType
+    summary
+    createdAt
+    startedAt
+    pausedAt
+    finishedAt
   }
-  if (normalizedErrorType.includes("not-found")) {
-    return "NOT_FOUND";
+}`
+  }),
+  createOperationSpec({
+    operationName: "ListAutomations",
+    kind: "query",
+    inputSchema: z2.object({
+      limit: z2.number().positive().optional(),
+      order: jsonObjectSchema.optional(),
+      where: jsonObjectSchema.optional()
+    }),
+    cli: {
+      name: "list-automations",
+      path: ["automations", "list"],
+      description: "List automations with optional filters.",
+      resultKey: "automations",
+      options: [
+        numberOption({
+          inputKey: "limit",
+          flagName: "limit",
+          description: "Maximum number of automations to return."
+        }),
+        jsonOption({
+          inputKey: "order",
+          flagName: "order-json",
+          description: "GraphQL order object."
+        }),
+        jsonOption({
+          inputKey: "where",
+          flagName: "where-json",
+          description: "GraphQL filter object."
+        })
+      ]
+    },
+    mcp: { fileName: "listAutomations.graphql" },
+    document: `# Query to list automations with flat fields only (no nested objects)
+# Excludes config and agents for MCP tool simplicity
+query ListAutomations(
+  $limit: Float
+  $order: AutomationsOrder
+  $where: AutomationsWhereInput
+) {
+  automations(limit: $limit, order: $order, where: $where) {
+    id
+    name
+    organizationId
+    createdAt
+    updatedAt
+    environment
+    lastSavedAt
+    publishedVersionId
+    draftVersionId
   }
-  if (isCustomerUsageError(appError)) {
-    return "BAD_USER_INPUT";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomations",
+    kind: "query",
+    inputSchema: z2.object({
+      ids: z2.array(z2.string().min(1)).min(1)
+    }),
+    cli: {
+      name: "get-automations",
+      path: ["automations", "get"],
+      description: "Fetch one or more automations by IDs.",
+      resultKey: "automations",
+      options: [
+        stringArrayOption({
+          inputKey: "ids",
+          flagName: "ids",
+          description: "Automation IDs.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "automations.graphql" },
+    document: `# Query to fetch automations with flat fields only (no nested objects)
+# Excludes config and agents for MCP tool simplicity
+query GetAutomations($ids: [ID!]!) {
+  automations(ids: $ids) {
+    id
+    name
+    organizationId
+    createdAt
+    updatedAt
+    environment
+    lastSavedAt
+    publishedVersionId
+    draftVersionId
   }
-  return "INTERNAL_SERVER_ERROR";
-}
-function getStatusCodeFromGraphQLErrorCode(code) {
-  switch (code) {
-    case "BAD_USER_INPUT": {
-      return 400;
-    }
-    case "UNAUTHORIZED": {
-      return 401;
-    }
-    case "FORBIDDEN": {
-      return 403;
-    }
-    case "NOT_FOUND": {
-      return 404;
-    }
-    case "INTERNAL_SERVER_ERROR": {
-      return 500;
-    }
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAvailableCommands",
+    kind: "query",
+    inputSchema: z2.object({
+      env: z2.string().min(1)
+    }),
+    cli: {
+      name: "get-available-commands",
+      path: ["catalog", "commands"],
+      description: "Fetch available command definitions by environment.",
+      resultKey: "availableCommands",
+      options: [
+        stringOption({
+          inputKey: "env",
+          flagName: "env",
+          description: "Environment name.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "availableCommands.graphql" },
+    document: `# Query to fetch available command definitions by environment
+query GetAvailableCommands($env: AvailableCommandsEnv!) {
+  availableCommands(env: $env) {
+    id
+    description
+    inputSchema
   }
-}
-function getGraphQLErrorMessage({ code, apiMessage }) {
-  switch (code) {
-    case "BAD_USER_INPUT":
-    case "NOT_FOUND":
-    case "INTERNAL_SERVER_ERROR": {
-      return apiMessage;
-    }
-    case "UNAUTHORIZED": {
-      return "Unauthorized";
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAvailableModels",
+    kind: "query",
+    inputSchema: z2.object({
+      agentId: z2.string().min(1)
+    }),
+    cli: {
+      name: "get-available-models",
+      path: ["catalog", "models"],
+      description: "Fetch available model definitions for an agent.",
+      resultKey: "availableModels",
+      options: [
+        stringOption({
+          inputKey: "agentId",
+          flagName: "agent-id",
+          description: "Agent ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "availableModels.graphql" },
+    document: `# Query to fetch available model definitions and pools for a specific agent
+query GetAvailableModels($agentId: String!) {
+  availableModels(agentId: $agentId) {
+    availableModelPools {
+      name
+      poolId
+      models {
+        id
+        name
+        description
+        status
+        provider
+      }
     }
-    case "FORBIDDEN": {
-      return "Forbidden";
+    allAvailableModels {
+      id
+      name
+      description
+      status
+      provider
     }
   }
-}
-function getGraphQLAppErrorCode({ code, apiCode }) {
-  if (code === "INTERNAL_SERVER_ERROR" || code === "UNAUTHORIZED" || code === "FORBIDDEN") {
-    return code;
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAvailableTools",
+    kind: "query",
+    inputSchema: z2.object({
+      env: z2.string().min(1),
+      automationId: z2.string().min(1).optional()
+    }),
+    cli: {
+      name: "get-available-tools",
+      path: ["catalog", "tools"],
+      description: "Fetch available tool definitions by environment.",
+      resultKey: "availableTools",
+      options: [
+        stringOption({
+          inputKey: "env",
+          flagName: "env",
+          description: "Environment name.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Optional automation ID."
+        })
+      ]
+    },
+    mcp: { fileName: "availableTools.graphql" },
+    document: `# Query to fetch available tool definitions by environment
+query GetAvailableTools($env: AvailableCommandsEnv!, $automationId: String) {
+  availableTools(env: $env, automationId: $automationId) {
+    id
+    description
+    inputSchema
   }
-  return apiCode;
-}
-function normalizeErrorCodeSegment(value) {
-  return value.trim().toUpperCase().replaceAll(/[^\dA-Z]+/gu, "_").replaceAll(/^_+/gu, "").replaceAll(/_+$/gu, "");
-}
-function getStatusCodeForAppErrorFromAppError(appError) {
-  const statusCodeFromCode = getStatusCodeFromAppErrorCode(appError.statusCode);
-  if (statusCodeFromCode !== void 0) {
-    return statusCodeFromCode;
+}`
+  }),
+  createOperationSpec({
+    operationName: "CreateAutomation",
+    kind: "mutation",
+    inputSchema: z2.object({
+      input: jsonObjectSchema
+    }),
+    cli: {
+      name: "create-automation",
+      path: ["automations", "create"],
+      description: "Create a draft automation.",
+      resultKey: "createAutomation",
+      options: [
+        jsonOption({
+          inputKey: "input",
+          flagName: "input-json",
+          description: "CreateAutomationInput payload.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "createAutomation.graphql" },
+    document: `# Mutation to create a draft automation with optional initial values
+# Returns flat fields only for MCP tool simplicity
+mutation CreateAutomation($input: CreateAutomationInput!) {
+  createAutomation(input: $input) {
+    id
+    name
+    organizationId
+    createdAt
+    updatedAt
+    environment
+    lastSavedAt
+    publishedVersionId
+    draftVersionId
   }
-  if (isCustomerUsageError(appError)) {
-    return 400;
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetGraphqlSchema",
+    kind: "query",
+    inputSchema: z2.object({}),
+    cli: {
+      name: "get-graphql-schema",
+      path: ["graphql", "schema"],
+      description: "Fetch GraphQL schema metadata.",
+      resultKey: "graphqlSchema",
+      options: []
+    },
+    mcp: { fileName: "graphqlSchema.graphql" },
+    document: `# Query to fetch full GraphQL schema metadata.
+# Uses the first-class graphqlSchema query field to avoid __schema validation
+# issues in MCP tool-load paths while still returning introspection JSON.
+# Response can be large: call sparingly (typically once per task/session) and
+# reuse cached results.
+query GetGraphqlSchema {
+  graphqlSchema
+}`
+  }),
+  createOperationSpec({
+    operationName: "PauseAutomationRun",
+    kind: "mutation",
+    inputSchema: z2.object({
+      automationRunId: z2.string().min(1)
+    }),
+    cli: {
+      name: "pause-automation-run",
+      path: ["automation-runs", "pause"],
+      description: "Pause an automation run.",
+      resultKey: "pauseAutomationRun",
+      options: [
+        stringOption({
+          inputKey: "automationRunId",
+          flagName: "automation-run-id",
+          description: "Automation run ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "pauseAutomationRun.graphql" },
+    document: `# Mutation to pause an automation run
+mutation PauseAutomationRun($automationRunId: ID!) {
+  pauseAutomationRun(automationRunId: $automationRunId)
+}`
+  }),
+  createOperationSpec({
+    operationName: "RerunAutomation",
+    kind: "mutation",
+    inputSchema: z2.object({
+      automationRunId: z2.string().min(1),
+      additionalPrompt: z2.string().min(1).optional(),
+      idempotencyKey: z2.string().min(1)
+    }),
+    cli: {
+      name: "rerun-automation",
+      path: ["automation-runs", "rerun"],
+      description: "Rerun an existing automation run.",
+      resultKey: "rerunAutomation",
+      options: [
+        stringOption({
+          inputKey: "automationRunId",
+          flagName: "automation-run-id",
+          description: "Automation run ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "additionalPrompt",
+          flagName: "additional-prompt",
+          description: "Optional prompt appended to the rerun."
+        }),
+        stringOption({
+          inputKey: "idempotencyKey",
+          flagName: "idempotency-key",
+          description: "Idempotency key for the rerun request.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "rerunAutomation.graphql" },
+    document: `# Mutation to rerun an existing automation run
+mutation RerunAutomation(
+  $automationRunId: ID!
+  $additionalPrompt: String
+  $idempotencyKey: String!
+) {
+  rerunAutomation(
+    automationRunId: $automationRunId
+    additionalPrompt: $additionalPrompt
+    idempotencyKey: $idempotencyKey
+  ) {
+    automationRunId
+    workflowId
+    workflowRunId
   }
-  return 500;
-}
-function normalizeUserFacingErrorCode({ type, fallbackCode, prefix }) {
-  if (!type) {
-    return fallbackCode;
+}`
+  }),
+  createOperationSpec({
+    operationName: "ResumeAutomationRun",
+    kind: "mutation",
+    inputSchema: z2.object({
+      automationRunId: z2.string().min(1),
+      message: z2.string().min(1).optional()
+    }),
+    cli: {
+      name: "resume-automation-run",
+      path: ["automation-runs", "resume"],
+      description: "Resume a paused automation run.",
+      resultKey: "resumeAutomationRun",
+      options: [
+        stringOption({
+          inputKey: "automationRunId",
+          flagName: "automation-run-id",
+          description: "Automation run ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "message",
+          flagName: "message",
+          description: "Optional resume message."
+        })
+      ]
+    },
+    mcp: { fileName: "resumeAutomationRun.graphql" },
+    document: `# Mutation to resume an automation run
+mutation ResumeAutomationRun($automationRunId: ID!, $message: String) {
+  resumeAutomationRun(automationRunId: $automationRunId, message: $message)
+}`
+  }),
+  createOperationSpec({
+    operationName: "RunDraftAutomation",
+    kind: "mutation",
+    inputSchema: z2.object({
+      draftAutomationId: z2.string().min(1),
+      agentId: z2.string().min(1),
+      idempotencyKey: z2.string().min(1),
+      input: z2.unknown().optional(),
+      additionalPrompt: z2.string().min(1).optional()
+    }),
+    cli: {
+      name: "run-draft-automation",
+      path: ["automations", "run-draft"],
+      description: "Run a draft automation with an explicit trigger agent.",
+      resultKey: "runDraftAutomation",
+      options: [
+        stringOption({
+          inputKey: "draftAutomationId",
+          flagName: "draft-automation-id",
+          description: "Draft automation ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "agentId",
+          flagName: "agent-id",
+          description: "Trigger agent ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "idempotencyKey",
+          flagName: "idempotency-key",
+          description: "Idempotency key for the run request.",
+          required: true
+        }),
+        jsonOption({
+          inputKey: "input",
+          flagName: "input-json",
+          description: "Optional JSON input payload."
+        }),
+        stringOption({
+          inputKey: "additionalPrompt",
+          flagName: "additional-prompt",
+          description: "Optional prompt appended to the run."
+        })
+      ]
+    },
+    mcp: { fileName: "runDraftAutomation.graphql" },
+    document: `# Mutation to run a draft automation with an explicit agent.
+# \`draftAutomationId\` is the draft automation entity ID (\`Automation.id\`), not \`draftVersionId\`.
+mutation RunDraftAutomation(
+  $draftAutomationId: ID!
+  $agentId: ID!
+  $idempotencyKey: String!
+  $input: JSON
+  $additionalPrompt: String
+) {
+  runDraftAutomation(
+    draftAutomationId: $draftAutomationId
+    agentId: $agentId
+    idempotencyKey: $idempotencyKey
+    input: $input
+    additionalPrompt: $additionalPrompt
+  ) {
+    automationRunId
+    workflowId
+    workflowRunId
   }
-  const normalized = normalizeErrorCodeSegment(type);
-  if (normalized.length === 0) {
-    return fallbackCode;
+}`
+  }),
+  createOperationSpec({
+    operationName: "StopAutomationRun",
+    kind: "mutation",
+    inputSchema: z2.object({
+      automationRunId: z2.string().min(1)
+    }),
+    cli: {
+      name: "stop-automation-run",
+      path: ["automation-runs", "stop"],
+      description: "Stop an automation run.",
+      resultKey: "stopAutomationRun",
+      options: [
+        stringOption({
+          inputKey: "automationRunId",
+          flagName: "automation-run-id",
+          description: "Automation run ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "stopAutomationRun.graphql" },
+    document: `# Mutation to stop an automation run
+mutation StopAutomationRun($automationRunId: ID!) {
+  stopAutomationRun(automationRunId: $automationRunId)
+}`
+  }),
+  createOperationSpec({
+    operationName: "UpdateAutomationById",
+    kind: "mutation",
+    inputSchema: z2.object({
+      id: z2.string().min(1),
+      input: jsonObjectSchema
+    }),
+    cli: {
+      name: "update-automation-by-id",
+      path: ["automations", "update"],
+      description: "Update an automation.",
+      resultKey: "updateAutomation",
+      options: [
+        stringOption({
+          inputKey: "id",
+          flagName: "id",
+          description: "Automation ID.",
+          required: true
+        }),
+        jsonOption({
+          inputKey: "input",
+          flagName: "input-json",
+          description: "UpdateAutomationInput payload.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "updateAutomation.graphql" },
+    document: `# Mutation to update an automation
+# Returns only id and lastSavedAt for MCP tool simplicity
+mutation UpdateAutomationById($id: ID!, $input: UpdateAutomationInput!) {
+  updateAutomation(id: $id, input: $input) {
+    id
+    lastSavedAt
+  }
+}`
+  })
+];
+
+// src/program.ts
+import { Command as Command2, InvalidArgumentError as InvalidArgumentError2, Option as Option2 } from "commander";
+
+// src/api.ts
+import { z as z3 } from "zod";
+var OTTO_AUTHORIZATION_HEADER_NAME = "X-Otto-Authorization";
+var OTTO_AUTHORIZATION_ISSUER = "magical:otto";
+var workosOrganizationsResponseSchema = z3.object({
+  organizations: z3.array(
+    z3.object({
+      id: z3.string().min(1),
+      name: z3.string().min(1),
+      primaryDomain: z3.string().nullable().optional()
+    })
+  ),
+  success: z3.boolean()
+});
+var workosUserSchema = z3.object({
+  email: z3.string().nullable(),
+  id: z3.string().min(1)
+});
+var nangoIntegrationWireSchema = z3.object({
+  // eslint-disable-next-line @typescript-eslint/naming-convention -- mirrors Nango REST payload
+  unique_key: z3.string().min(1)
+}).passthrough().transform((data) => ({
+  ...data,
+  uniqueKey: data.unique_key
+}));
+var nangoIntegrationsResponseSchema = z3.array(nangoIntegrationWireSchema);
+var organizationAuthenticationSchema = z3.object({
+  id: z3.string().min(1),
+  type: z3.string().min(1),
+  connectionId: z3.string().nullable().optional(),
+  providerConfigKey: z3.string().nullable().optional(),
+  description: z3.string().nullable().optional(),
+  hostname: z3.string().nullable().optional()
+}).passthrough();
+var organizationAuthenticationsResponseSchema = z3.object({
+  authentications: z3.array(organizationAuthenticationSchema),
+  success: z3.boolean()
+});
+var graphQlResponseSchema = z3.object({
+  data: z3.record(z3.string(), z3.unknown()).optional(),
+  errors: z3.array(
+    z3.object({
+      message: z3.string().min(1)
+    })
+  ).optional()
+});
+var apiErrorResponseSchema = z3.object({
+  errors: z3.array(
+    z3.object({
+      message: z3.string().min(1)
+    })
+  ).optional(),
+  message: z3.string().min(1).optional()
+});
+function getApiErrorDetail(responseBody) {
+  const parsedResponse = apiErrorResponseSchema.safeParse(responseBody);
+  if (!parsedResponse.success) {
+    return null;
   }
-  const normalizedPrefix = prefix ? normalizeErrorCodeSegment(prefix) : void 0;
-  if (!normalizedPrefix) {
-    return normalized;
+  if (parsedResponse.data.message) {
+    return parsedResponse.data.message;
   }
-  if (normalized.startsWith(`${normalizedPrefix}_`)) {
-    return normalized;
+  if (!parsedResponse.data.errors || parsedResponse.data.errors.length === 0) {
+    return null;
   }
-  return `${normalizedPrefix}_${normalized}`;
-}
-function toUserFacingApiErrorFromAppError({ appError, correlationId, statusCode }) {
-  const resolvedStatusCode = statusCode ?? getStatusCodeForAppErrorFromAppError(appError);
-  const message = resolveApiMessage({
-    appError,
-    statusCode: resolvedStatusCode
-  });
-  const suggestedAction = resolveSuggestedAction({
-    appError,
-    statusCode: resolvedStatusCode
-  });
-  const details = resolveApiDetails({
-    appError,
-    statusCode: resolvedStatusCode
-  });
-  return {
-    code: resolveApiErrorCode({
-      appError,
-      statusCode: resolvedStatusCode
-    }),
-    message,
-    correlationId,
-    suggestedAction,
-    ...details ? { details } : {}
-  };
-}
-function toUserFacingGraphQLErrorFromAppError({ appError, correlationId }) {
-  const code = resolveGraphQLErrorCode(appError);
-  const statusCode = getStatusCodeFromGraphQLErrorCode(code);
-  const apiError = toUserFacingApiErrorFromAppError({
-    appError,
-    correlationId,
-    statusCode
-  });
-  return {
-    code,
-    errorCode: getGraphQLAppErrorCode({ code, apiCode: apiError.code }),
-    message: getGraphQLErrorMessage({ code, apiMessage: apiError.message }),
-    correlationId
-  };
-}
-
-// ../common/dist/src/stdlib/error.js
-var INTERNAL_STACK_PATHS = [
-  "/src/stdlib/result.util.ts",
-  "/src/stdlib/error.ts"
-];
-function stripInternalFrames(stack, internalFrames) {
-  const lines = stack.split("\n");
-  return lines.filter((line) => !internalFrames.some((internalFrame) => line.includes(internalFrame)));
+  return parsedResponse.data.errors.map((error) => error.message).join("\n");
 }
-var ORDERED_APP_ERROR_CATEGORIES = [
-  "internal_platform",
-  "customer_usage",
-  "third_party"
-];
-function isAppErrorCategory(category) {
-  return typeof category === "string" && // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-  ORDERED_APP_ERROR_CATEGORIES.includes(category);
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/u, "");
 }
-function isNonEmptyAppErrorCategoryArray(categories) {
-  return Array.isArray(categories) && categories.length > 0 && categories.every(isAppErrorCategory);
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-var APP_ERROR_SEVERITIES = ["warn", "error", "fatal"];
-function isAppErrorCode(code) {
-  return typeof code === "number" && Number.isInteger(code) && code >= 400 && code <= 599;
+function decodeJwtPayload(token) {
+  const [, payloadSegment] = token.split(".");
+  if (!payloadSegment) {
+    return null;
+  }
+  const payloadResult = safeJsonParse(
+    Buffer.from(payloadSegment, "base64url").toString("utf8")
+  );
+  if (isErr(payloadResult)) {
+    return null;
+  }
+  return isRecord2(payloadResult.value) ? payloadResult.value : null;
 }
-function isAppErrorSeverity(severity) {
-  return typeof severity === "string" && // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
-  APP_ERROR_SEVERITIES.includes(severity);
+function isOttoAuthorizationToken(token) {
+  return decodeJwtPayload(token)?.["iss"] === OTTO_AUTHORIZATION_ISSUER;
 }
-var AppError = class _AppError extends Error {
-  type;
-  categories;
-  severity;
-  statusCode;
-  suggestedAction;
-  nonRetryable;
-  details;
-  constructor({ type, categories, severity, statusCode, code, message, suggestedAction, cause, nonRetryable, stack, internalFrames, ...details }) {
-    super(_AppError.resolveMessage(message, cause, type), { cause });
-    this.type = type;
-    this.name = type;
-    this.details = details;
-    this.categories = categories ?? _AppError.extractCategoriesFromCause(cause);
-    this.severity = severity ?? _AppError.extractSeverityFromCause(cause);
-    this.statusCode = statusCode ?? code ?? _AppError.extractStatusCodeFromCause(cause);
-    this.suggestedAction = suggestedAction ?? _AppError.extractSuggestedActionFromCause(cause);
-    this.nonRetryable = nonRetryable ?? false;
-    _AppError.applyStack(this, stack, internalFrames);
-  }
-  static resolveMessage(message, cause, type) {
-    if (message) {
-      return message;
-    }
-    if (cause instanceof Error) {
-      return cause.message;
+function applyAuthenticationHeaders({
+  accessToken,
+  allowOttoAuthorization,
+  headers,
+  impersonatedOrganizationId,
+  organizationId
+}) {
+  if (!isOttoAuthorizationToken(accessToken)) {
+    headers.set("authorization", `Bearer ${accessToken}`);
+    if (impersonatedOrganizationId) {
+      headers.set("x-organization-id", impersonatedOrganizationId);
     }
-    return type;
+    return;
   }
-  static getInheritedCauseField(cause, extractor, seen = /* @__PURE__ */ new Set()) {
-    if (!cause || typeof cause !== "object" || seen.has(cause)) {
-      return void 0;
-    }
-    const causeRecord = cause;
-    const extractedValue = extractor(causeRecord);
-    if (extractedValue !== void 0) {
-      return extractedValue;
+  if (!allowOttoAuthorization) {
+    throw new CliError(
+      "Otto authorization is only supported for GraphQL requests."
+    );
+  }
+  if (!organizationId) {
+    throw new CliError("Otto authorization requires an organization ID.");
+  }
+  headers.set(OTTO_AUTHORIZATION_HEADER_NAME, `Bearer ${accessToken}`);
+  headers.set("x-organization-id", organizationId);
+}
+function createMagicalApiClient({
+  apiBaseUrl,
+  fetchFn = fetch
+}) {
+  const resolveApiBaseUrl = typeof apiBaseUrl === "string" ? () => apiBaseUrl : apiBaseUrl;
+  async function fetchJson({
+    accessToken,
+    impersonatedOrganizationId,
+    allowOttoAuthorization,
+    path: path7,
+    init,
+    organizationId
+  }) {
+    const url = `${trimTrailingSlash(await resolveApiBaseUrl())}${path7}`;
+    const headers = new Headers(init?.headers);
+    applyAuthenticationHeaders({
+      accessToken,
+      ...allowOttoAuthorization ? { allowOttoAuthorization } : {},
+      headers,
+      ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+      ...organizationId ? { organizationId } : {}
+    });
+    const response = await fetchFn(url, {
+      ...init,
+      headers
+    }).catch((error) => {
+      throw new CliError(
+        `Failed to reach Magical API at ${url}. Check your configured base URL and make sure service-main is running.`,
+        { cause: error }
+      );
+    });
+    const responseBody = await response.json().catch((error) => {
+      if (!response.ok) {
+        throw new CliError(
+          `Magical API request to ${url} failed with status ${response.status}.`,
+          {
+            cause: error
+          }
+        );
+      }
+      throw new CliError(
+        `Magical API returned a non-JSON response for ${url}.`,
+        {
+          cause: error
+        }
+      );
+    });
+    if (!response.ok) {
+      const errorDetail = getApiErrorDetail(responseBody);
+      throw new CliError(
+        `Magical API request to ${url} failed with status ${response.status}${errorDetail ? `: ${errorDetail}` : "."}`
+      );
     }
-    return _AppError.getInheritedCauseField(causeRecord["cause"], extractor, new Set(seen).add(cause));
+    return responseBody;
   }
-  static extractCategoriesFromCause(cause) {
-    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
-      const { categories } = causeRecord;
-      if (isNonEmptyAppErrorCategoryArray(categories)) {
-        return categories;
+  return {
+    async executeGraphQl({
+      accessToken,
+      impersonatedOrganizationId,
+      organizationId,
+      query,
+      resultKey,
+      variables
+    }) {
+      const headers = new Headers();
+      headers.set("content-type", "application/json");
+      const parsedResponse = graphQlResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          allowOttoAuthorization: true,
+          ...organizationId ? { organizationId } : {},
+          path: "/graphql",
+          init: {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+              query,
+              variables
+            })
+          }
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("GraphQL response payload was invalid.");
+      }
+      if (parsedResponse.data.errors && parsedResponse.data.errors.length > 0) {
+        throw new CliError(
+          parsedResponse.data.errors.map((error) => error.message).join("\n")
+        );
+      }
+      return parsedResponse.data.data?.[resultKey] ?? null;
+    },
+    async fetchOrganizations({ accessToken }) {
+      const parsedResponse = workosOrganizationsResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          path: "/workos/organizations"
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Organization list payload was invalid.");
+      }
+      return parsedResponse.data.organizations.map((organization) => ({
+        id: organization.id,
+        name: organization.name,
+        primaryDomain: organization.primaryDomain ?? null
+      }));
+    },
+    async fetchUser({
+      accessToken,
+      organizationId,
+      userId
+    }) {
+      const parsedResponse = workosUserSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          ...organizationId ? { organizationId } : {},
+          path: `/workos/user/${userId}`
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("User payload was invalid.");
       }
-      return void 0;
-    }) ?? ["internal_platform"];
-  }
-  static extractSeverityFromCause(cause) {
-    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
-      const { severity } = causeRecord;
-      return isAppErrorSeverity(severity) ? severity : void 0;
-    }) ?? "error";
-  }
-  static extractStatusCodeFromCause(cause) {
-    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
-      const { statusCode } = causeRecord;
-      if (isAppErrorCode(statusCode)) {
-        return statusCode;
+      return parsedResponse.data;
+    },
+    async listNangoIntegrations({
+      accessToken,
+      impersonatedOrganizationId,
+      organizationId
+    }) {
+      const parsedResponse = nangoIntegrationsResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: "/nango/integrations"
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Nango integrations payload was invalid.");
       }
-      const { code: legacyCode } = causeRecord;
-      return isAppErrorCode(legacyCode) ? legacyCode : void 0;
-    });
-  }
-  /** @deprecated Use statusCode instead. */
-  get code() {
-    return this.statusCode;
-  }
-  static extractSuggestedActionFromCause(cause) {
-    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
-      const { suggestedAction } = causeRecord;
-      if (typeof suggestedAction !== "string") {
-        return void 0;
+      return parsedResponse.data;
+    },
+    async listNangoAuthentications({
+      accessToken,
+      impersonatedOrganizationId,
+      organizationId
+    }) {
+      const parsedResponse = organizationAuthenticationsResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: "/authentications/organization?type=nangoConnection"
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Organization authentications payload was invalid.");
       }
-      const trimmedSuggestedAction = suggestedAction.trim();
-      return trimmedSuggestedAction.length > 0 ? trimmedSuggestedAction : void 0;
-    });
-  }
-  static applyStack(error, stack, internalFrames) {
-    if (stack) {
-      error.stack = stack;
+      return parsedResponse.data.authentications;
     }
-    error.stack &&= stripInternalFrames(error.stack, [
-      ...INTERNAL_STACK_PATHS,
-      ...internalFrames ?? []
-    ]).join("\n");
-  }
-  toApiError({ correlationId }) {
-    return toUserFacingApiError({
-      error: this,
-      correlationId,
-      statusCode: getStatusCodeForAppError(this)
-    });
-  }
-  toGqlError({ correlationId }) {
-    return toUserFacingGraphQLError({
-      error: this,
-      correlationId
-    });
-  }
-};
-function toAppError(error) {
-  return error instanceof AppError ? error : new AppError(error);
-}
-function getStatusCodeForAppError(error) {
-  const appError = toAppError(error);
-  return getStatusCodeForAppErrorFromAppError(appError);
-}
-function toUserFacingApiError({ error, correlationId, statusCode }) {
-  const appError = toAppError(error);
-  return toUserFacingApiErrorFromAppError({
-    appError,
-    correlationId,
-    statusCode
-  });
-}
-function toUserFacingGraphQLError({ error, correlationId }) {
-  const appError = toAppError(error);
-  return toUserFacingGraphQLErrorFromAppError({
-    appError,
-    correlationId
-  });
+  };
 }
 
-// ../common/dist/src/stdlib/result.util.js
-var Result;
-(function(Result2) {
-  function partition(responses) {
-    const oks = responses.filter((resp) => resp._tag === "Ok").map((resp) => resp.value);
-    const errs = responses.filter((resp) => resp._tag === "Err").map((resp) => resp.error);
-    return [oks, errs];
-  }
-  Result2.partition = partition;
-  async function promiseAllAndPartition(promises) {
-    const results = await Promise.all(promises);
-    return partition(results);
-  }
-  Result2.promiseAllAndPartition = promiseAllAndPartition;
-  function unwrapOrThrow(result) {
-    if (isErr(result)) {
-      throw result.error;
-    }
-    return result.value;
-  }
-  Result2.unwrapOrThrow = unwrapOrThrow;
-  async function all(promises) {
-    const results = await fromThrowable(async () => Promise.all(promises.map(async (promise) => {
-      const result = await promise;
-      if (isErr(result)) {
-        throw result.error;
-      }
-      return result;
-    })), "unknown-error");
-    if (isErr(results)) {
-      return ErrFromThrowable(results.error.cause);
-    }
-    return Ok(results.value.map((r) => r.value));
-  }
-  Result2.all = all;
-  function andThenSync(fnFirst, ...fns) {
-    let result = fnFirst();
-    const values = [];
-    for (const fn of fns) {
-      if (isErr(result)) {
-        return result;
-      }
-      values.unshift(result.value);
-      result = fn(...values);
-    }
-    return result;
+// src/config.ts
+import os from "os";
+import path from "path";
+var DEFAULT_MAGICAL_API_URL = "https://api-agt.getmagical.io";
+var DEFAULT_WORKOS_API_URL = "https://api.workos.com";
+var DEFAULT_WORKOS_CLIENT_ID = "client_01JJZ6XJ1RF248P20WF63M4VAM";
+var DEFAULT_STAGING_WORKOS_CLIENT_ID = "client_01JJZ6X26BGFBT8AC303XPQ9EQ";
+var DEFAULT_KEYCHAIN_SERVICE_NAME = "@getmagical/mcp-cli";
+var DEFAULT_CLI_DIST_TAG = "latest";
+var DEFAULT_CLI_NPM_REGISTRY_URL = "https://registry.npmjs.org/";
+var CLI_CONFIG_DIRECTORY_NAME = "magical-mcp-cli";
+var CLI_ACCESS_TOKEN_FILE_NAME = "access-token.txt";
+var CLI_STATE_FILE_NAME = "state.json";
+var CLI_SETTINGS_FILE_NAME = "settings.json";
+var CLI_REFRESH_TOKEN_FILE_NAME = "refresh-tokens.json";
+function resolvePlatformConfigDirectory() {
+  const customConfigDirectory = process.env["MAGICAL_CLI_CONFIG_DIR"];
+  if (customConfigDirectory) {
+    return customConfigDirectory;
   }
-  Result2.andThenSync = andThenSync;
-  async function andThen(fnFirst, ...fns) {
-    let result = await fnFirst();
-    const values = [];
-    for (const fn of fns) {
-      if (isErr(result)) {
-        return result;
-      }
-      values.unshift(result.value);
-      result = await fn(...values);
-    }
-    return result;
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support");
   }
-  Result2.andThen = andThen;
-})(Result || (Result = {}));
-function Ok(value) {
-  if (arguments.length === 0) {
-    return {
-      _tag: "Ok",
-      value: void 0
-    };
+  if (process.platform === "win32") {
+    const appDataDirectory = process.env["APPDATA"];
+    return appDataDirectory ?? path.join(os.homedir(), "AppData", "Roaming");
   }
-  return {
-    _tag: "Ok",
-    value
-  };
+  return process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config");
 }
-function Err(error) {
-  return {
-    _tag: "Err",
-    error: new AppError(error)
-  };
+function resolveRefreshTokenStoreKind() {
+  return process.env["MAGICAL_CLI_REFRESH_TOKEN_STORE"] === "file" ? "file" : "keytar";
 }
-function ErrFromThrowable(error) {
+function getRuntimeConfig() {
+  const configDirectory = path.join(
+    resolvePlatformConfigDirectory(),
+    CLI_CONFIG_DIRECTORY_NAME
+  );
   return {
-    _tag: "Err",
-    error
+    accessTokenFilePath: path.join(configDirectory, CLI_ACCESS_TOKEN_FILE_NAME),
+    cliDistTag: process.env["MAGICAL_CLI_DIST_TAG"] ?? DEFAULT_CLI_DIST_TAG,
+    magicalApiUrl: DEFAULT_MAGICAL_API_URL,
+    npmRegistryUrl: process.env["MAGICAL_CLI_NPM_REGISTRY_URL"] ?? DEFAULT_CLI_NPM_REGISTRY_URL,
+    refreshTokenFilePath: path.join(
+      configDirectory,
+      CLI_REFRESH_TOKEN_FILE_NAME
+    ),
+    refreshTokenStoreKind: resolveRefreshTokenStoreKind(),
+    stateFilePath: path.join(configDirectory, CLI_STATE_FILE_NAME),
+    workosApiUrl: DEFAULT_WORKOS_API_URL,
+    workosClientId: DEFAULT_WORKOS_CLIENT_ID,
+    keychainServiceName: DEFAULT_KEYCHAIN_SERVICE_NAME
   };
 }
-function isErr(result) {
-  return result._tag === "Err";
-}
-function fromThrowable(fn, errorType, errorInfo) {
-  try {
-    const result = fn();
-    if (result && typeof result.then === "function") {
-      return result.then((value) => Ok(value)).catch((err) => Err({
-        ...errorInfo,
-        type: errorType,
-        cause: err
-      }));
-    }
-    return Ok(result);
-  } catch (err) {
-    return Err({
-      ...errorInfo,
-      type: errorType,
-      cause: err
-    });
-  }
-}
-
-// ../common/dist/src/stdlib/json.util.js
-function safeJsonParse(json) {
-  try {
-    return Ok(JSON.parse(json));
-  } catch (error) {
-    console.warn("Failed to parse JSON", { error, json });
-    return Err({ type: "invalid-json", cause: error, json });
-  }
+function requireWorkosClientId(config) {
+  return config.workosClientId;
 }
 
 // src/settings.ts
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import path2 from "path";
 import { z as z4 } from "zod";
 var cliSettingsSchema = z4.object({
   env: z4.object({
@@ -9153,6 +9272,22 @@ function resolveOpenCommand(url) {
 
 // src/program-session.ts
 import { readFile as readFile2, rm as rm2 } from "fs/promises";
+
+// ../common/dist/src/stdlib/url.utils.js
+var import_handlebars = __toESM(require_lib(), 1);
+function safeUrlConstructor(url, baseUrl) {
+  try {
+    return Ok(baseUrl ? new URL(url, baseUrl) : new URL(url));
+  } catch {
+    return Err({
+      type: "invalid-url",
+      message: `Invalid URL`,
+      url
+    });
+  }
+}
+
+// src/program-session.ts
 async function withOrgScopedAccessToken({
   dependencies,
   organizationId,
@@ -9217,10 +9352,20 @@ async function loadDirectAccessToken({
   if (!accessTokenFileContents) {
     return null;
   }
-  const claims = dependencies.authClient.decodeAccessTokenClaims(
-    accessTokenFileContents
+  const claimsResult = fromThrowable(
+    () => dependencies.authClient.decodeAccessTokenClaims(accessTokenFileContents),
+    "decode-otto-session-access-token-failed"
   );
+  if (isErr(claimsResult)) {
+    return null;
+  }
+  const claims = claimsResult.value;
   if (isExpiredAccessTokenClaims(claims)) {
+    if (claims.iss === "magical:otto") {
+      throw new CliError(
+        "The Otto session authorization token expired. Start a new Otto session from Magical."
+      );
+    }
     return null;
   }
   if (claims.org_id && claims.org_id !== organizationId) {
@@ -9242,29 +9387,10 @@ import { spawn as spawn2 } from "child_process";
 import fs from "fs";
 import path3 from "path";
 import { fileURLToPath } from "url";
-
-// ../common/dist/src/stdlib/url.utils.js
-var import_handlebars = __toESM(require_lib(), 1);
-function safeUrlConstructor(url, baseUrl) {
-  try {
-    return Ok(baseUrl ? new URL(url, baseUrl) : new URL(url));
-  } catch {
-    return Err({
-      type: "invalid-url",
-      message: `Invalid URL`,
-      url
-    });
-  }
-}
-
-// src/self-update.ts
 var CLI_PACKAGE_NAME = "@getmagical/cli";
 var DEFAULT_CLI_DIST_TAG2 = "latest";
 var DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org/";
 var MANAGED_NODE_SUBPATH = "runtime/node";
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function resolveInstalledPackageRoot({
   entryFilePath,
   packageName
@@ -9305,154 +9431,6 @@ function resolveInstallPrefixFromPackageRoot(packageRootPath) {
     currentPath = parentPath;
   }
 }
-function readInstalledPackageVersion({
-  packageName,
-  packageRootPath
-}) {
-  const packageManifestPath2 = path3.join(packageRootPath, "package.json");
-  if (!fs.existsSync(packageManifestPath2)) {
-    throw new CliError(
-      `Installed package metadata was not found at ${packageManifestPath2}. Reinstall mgcl and try again.`
-    );
-  }
-  const packageManifestResult2 = safeJsonParse(
-    fs.readFileSync(packageManifestPath2, "utf8")
-  );
-  if (isErr(packageManifestResult2)) {
-    throw new CliError(`Failed to parse ${packageManifestPath2}.`, {
-      cause: packageManifestResult2.error.cause
-    });
-  }
-  const packageManifest = packageManifestResult2.value;
-  if (packageManifest.name !== packageName) {
-    throw new CliError(
-      `Expected installed package ${packageName} at ${packageManifestPath2}. Reinstall mgcl and try again.`
-    );
-  }
-  if (typeof packageManifest.version !== "string" || !packageManifest.version) {
-    throw new CliError(
-      `Installed package version is missing from ${packageManifestPath2}. Reinstall mgcl and try again.`
-    );
-  }
-  return packageManifest.version;
-}
-function parseVersionSegment(segment, version) {
-  if (!/^\d+$/u.test(segment)) {
-    throw new CliError(`Invalid CLI version "${version}".`);
-  }
-  return Number(segment);
-}
-function parseSemanticVersion(version) {
-  const normalizedVersion = version.trim().replace(/^v/u, "");
-  const [versionWithoutBuildMetadata = ""] = normalizedVersion.split("+");
-  if (!versionWithoutBuildMetadata) {
-    throw new CliError(`Invalid CLI version "${version}".`);
-  }
-  const [releasePart, prereleasePart] = versionWithoutBuildMetadata.split("-");
-  if (!releasePart) {
-    throw new CliError(`Invalid CLI version "${version}".`);
-  }
-  return {
-    prerelease: prereleasePart ? prereleasePart.split(".") : null,
-    release: releasePart.split(".").map((segment) => parseVersionSegment(segment, version))
-  };
-}
-function comparePrereleaseIdentifiers(left, right) {
-  const leftIsNumeric = /^\d+$/u.test(left);
-  const rightIsNumeric = /^\d+$/u.test(right);
-  if (leftIsNumeric && rightIsNumeric) {
-    return Number(left) - Number(right);
-  }
-  if (leftIsNumeric) {
-    return -1;
-  }
-  if (rightIsNumeric) {
-    return 1;
-  }
-  return left.localeCompare(right);
-}
-function compareSemanticVersions(leftVersion, rightVersion) {
-  const left = parseSemanticVersion(leftVersion);
-  const right = parseSemanticVersion(rightVersion);
-  const releaseLength = Math.max(left.release.length, right.release.length);
-  for (let index = 0; index < releaseLength; index += 1) {
-    const difference = (left.release[index] ?? 0) - (right.release[index] ?? 0);
-    if (difference !== 0) {
-      return difference;
-    }
-  }
-  if (!left.prerelease && !right.prerelease) {
-    return 0;
-  }
-  if (!left.prerelease) {
-    return 1;
-  }
-  if (!right.prerelease) {
-    return -1;
-  }
-  const prereleaseLength = Math.max(
-    left.prerelease.length,
-    right.prerelease.length
-  );
-  for (let index = 0; index < prereleaseLength; index += 1) {
-    const leftIdentifier = left.prerelease[index];
-    const rightIdentifier = right.prerelease[index];
-    if (leftIdentifier === void 0) {
-      return -1;
-    }
-    if (rightIdentifier === void 0) {
-      return 1;
-    }
-    const difference = comparePrereleaseIdentifiers(
-      leftIdentifier,
-      rightIdentifier
-    );
-    if (difference !== 0) {
-      return difference;
-    }
-  }
-  return 0;
-}
-async function fetchPublishedPackageVersion({
-  distTag,
-  fetchFn = fetch,
-  packageName,
-  registryUrl
-}) {
-  const distTagUrlResult = safeUrlConstructor(
-    `${registryUrl.replace(/\/?$/u, "/")}-/package/${encodeURIComponent(packageName)}/dist-tags`
-  );
-  if (isErr(distTagUrlResult)) {
-    throw new CliError(`Invalid npm registry URL "${registryUrl}".`);
-  }
-  const response = await fetchFn(distTagUrlResult.value, {
-    headers: {
-      accept: "application/json"
-    }
-  });
-  if (!response.ok) {
-    throw new CliError(
-      `Could not check the latest published mgcl version (status ${response.status}).`
-    );
-  }
-  const distTagsResult = safeJsonParse(await response.text());
-  if (isErr(distTagsResult)) {
-    throw new CliError("Could not parse the npm dist-tags response for mgcl.", {
-      cause: distTagsResult.error.cause
-    });
-  }
-  if (!isRecord2(distTagsResult.value)) {
-    throw new CliError("Could not parse the npm dist-tags response for mgcl.");
-  }
-  const distTags = distTagsResult.value;
-  const publishedVersion = distTags[distTag];
-  if (typeof publishedVersion !== "string" || publishedVersion.length === 0) {
-    throw new CliError(
-      `Could not find npm dist-tag "${distTag}" for ${packageName}.`
-    );
-  }
-  return publishedVersion;
-}
 function resolveNpmCommandFromPath() {
   return {
     argsPrefix: [],
@@ -9566,45 +9544,6 @@ async function selfUpdateInstalledCli({
     registryUrl
   });
 }
-async function getInstalledCliUpdateRequirement({
-  distTag = DEFAULT_CLI_DIST_TAG2,
-  entryFilePath = fileURLToPath(import.meta.url),
-  fetchFn = fetch,
-  packageName = CLI_PACKAGE_NAME,
-  registryUrl = DEFAULT_NPM_REGISTRY_URL
-} = {}) {
-  const packageRootPath = resolveInstalledPackageRoot({
-    entryFilePath,
-    packageName
-  });
-  if (!packageRootPath) {
-    return null;
-  }
-  const installedVersion = readInstalledPackageVersion({
-    packageName,
-    packageRootPath
-  });
-  const publishedVersionResult = await fromThrowable(
-    async () => fetchPublishedPackageVersion({
-      distTag,
-      fetchFn,
-      packageName,
-      registryUrl
-    }),
-    "cli-update-check-failed"
-  );
-  if (isErr(publishedVersionResult)) {
-    return null;
-  }
-  const publishedVersion = publishedVersionResult.value;
-  if (compareSemanticVersions(installedVersion, publishedVersion) >= 0) {
-    return null;
-  }
-  return {
-    installedVersion,
-    latestVersion: publishedVersion
-  };
-}
 
 // src/settings-command.ts
 import { Command, InvalidArgumentError, Option } from "commander";
@@ -9865,6 +9804,7 @@ var tokenErrorSchema = z6.object({
 });
 var accessTokenClaimsSchema = z6.object({
   exp: z6.number().int().positive().optional(),
+  iss: z6.string().min(1).optional(),
   org_id: z6.string().min(1).optional(),
   sid: z6.string().min(1).optional(),
   sub: z6.string().min(1)
@@ -10034,13 +9974,13 @@ function parseCommandOptionValue(rawValue, optionSpec) {
       return rawValue.split(",").map((value) => value.trim()).filter((value) => value.length > 0);
     }
     case "json": {
-      try {
-        return JSON.parse(rawValue);
-      } catch {
+      const parsedJson = safeJsonParse(rawValue);
+      if (isErr(parsedJson)) {
         throw new InvalidArgumentError2(
           `Expected valid JSON for --${optionSpec.flagName}.`
         );
       }
+      return parsedJson.value;
     }
     case "boolean": {
       return rawValue;
@@ -10110,6 +10050,13 @@ function requireLoggedInState(state) {
 function writeJsonOutput3(io, value) {
   io.info(JSON.stringify(value, null, 2));
 }
+function requireApiClientMethod(apiClient, key) {
+  const method = apiClient[key];
+  if (!method) {
+    throw new CliError(`CLI API client method "${key}" is not wired.`);
+  }
+  return method;
+}
 function collectOperationVariables(operationSpec, options) {
   const variables = Object.fromEntries(
     operationSpec.cli.options.flatMap((optionSpec) => {
@@ -10198,39 +10145,16 @@ async function handleSelfUpdate(dependencies, options) {
     `Updated mgcl via npm (${updateResult.packageSpecifier}) in ${updateResult.installPrefix}.`
   );
 }
-function isRootUpdateCommand(program2, actionCommand) {
-  return actionCommand.parent === program2 && actionCommand.name() === "update";
-}
-async function enforceLatestCliVersionIfNeeded({
-  dependencies,
-  program: program2,
-  actionCommand
-}) {
-  if (actionCommand === program2 || isRootUpdateCommand(program2, actionCommand)) {
-    return;
-  }
-  const updateRequirement = await dependencies.ensureLatestCliVersion?.();
-  if (!updateRequirement) {
-    return;
-  }
-  throw new CliError(
-    `mgcl ${updateRequirement.installedVersion} is outdated. Upgrade to ${updateRequirement.latestVersion} with "mgcl update", then rerun your command.`
-  );
-}
 async function handleOperationCommand(dependencies, operationSpec, commandOptions) {
-  const state = requireLoggedInState(await dependencies.stateStore.load());
-  const organization = resolveSelectedOrganization({
-    state,
-    ...commandOptions.org ? { organizationSelector: commandOptions.org } : {}
-  });
-  const variables = collectOperationVariables(operationSpec, commandOptions);
-  const { accessToken } = await withOrgScopedAccessToken({
+  const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({
     dependencies,
-    organizationId: organization.id,
-    state
+    options: commandOptions
   });
+  const variables = collectOperationVariables(operationSpec, commandOptions);
   const result = await dependencies.apiClient.executeGraphQl({
     accessToken,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id,
     query: operationSpec.document,
     resultKey: operationSpec.cli.resultKey,
     variables
@@ -10245,6 +10169,136 @@ async function handleOperationCommand(dependencies, operationSpec, commandOption
   }
   dependencies.io.info(formatHumanReadableOutput(result));
 }
+async function withSelectedOrganizationAndAccessToken({
+  dependencies,
+  options
+}) {
+  const state = requireLoggedInState(await dependencies.stateStore.load());
+  const organization = resolveSelectedOrganization({
+    state,
+    ...options.org ? { organizationSelector: options.org } : {}
+  });
+  const authenticatedOrganizationId = await resolveDirectAccessTokenOrganizationId({ dependencies });
+  const shouldImpersonateOrganization = authenticatedOrganizationId !== null && organization.id !== authenticatedOrganizationId;
+  const { accessToken } = await withOrgScopedAccessToken({
+    dependencies,
+    organizationId: shouldImpersonateOrganization && authenticatedOrganizationId ? authenticatedOrganizationId : organization.id,
+    state
+  });
+  return {
+    accessToken,
+    ...shouldImpersonateOrganization ? { impersonatedOrganizationId: organization.id } : {},
+    organization,
+    state
+  };
+}
+function writeCommandOutput({
+  dependencies,
+  json,
+  result
+}) {
+  if (json) {
+    writeJsonOutput3(dependencies.io, result);
+    return;
+  }
+  dependencies.io.info(formatHumanReadableOutput(result));
+}
+async function handleNangoIntegrationsListCommand(dependencies, options) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({ dependencies, options });
+  const listNangoIntegrations = requireApiClientMethod(
+    dependencies.apiClient,
+    "listNangoIntegrations"
+  );
+  const integrations = await listNangoIntegrations({
+    accessToken,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id
+  });
+  await saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: integrations
+  });
+}
+function normalizeListedNangoAuthentication(authentication) {
+  return {
+    id: authentication.id,
+    type: authentication.type,
+    ...authentication.connectionId === void 0 ? {} : { connectionId: authentication.connectionId },
+    ...authentication.providerConfigKey === void 0 ? {} : { providerConfigKey: authentication.providerConfigKey },
+    ...authentication.description === void 0 ? {} : { description: authentication.description },
+    ...authentication.hostname === void 0 ? {} : { hostname: authentication.hostname }
+  };
+}
+async function handleNangoAuthsListCommand(dependencies, options) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({ dependencies, options });
+  const listNangoAuthentications = requireApiClientMethod(
+    dependencies.apiClient,
+    "listNangoAuthentications"
+  );
+  const organizationAuthentications = await listNangoAuthentications({
+    accessToken,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id
+  });
+  const authentications = organizationAuthentications.filter((authentication) => {
+    if (options.integration && authentication.providerConfigKey !== options.integration) {
+      return false;
+    }
+    if (options.connectionId && authentication.connectionId !== options.connectionId) {
+      return false;
+    }
+    return true;
+  }).map(normalizeListedNangoAuthentication);
+  await saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: authentications
+  });
+}
+async function resolveDirectAccessTokenOrganizationId({
+  dependencies
+}) {
+  const { accessTokenFilePath } = dependencies.runtimeConfig;
+  if (!accessTokenFilePath) {
+    return null;
+  }
+  const accessToken = await readFile4(accessTokenFilePath, "utf8").then((value) => value.trim()).catch((error) => {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  });
+  if (!accessToken) {
+    return null;
+  }
+  try {
+    const claims = dependencies.authClient.decodeAccessTokenClaims(accessToken);
+    return claims.org_id ?? null;
+  } catch {
+    return null;
+  }
+}
+async function saveLastUsedOrganization({
+  dependencies,
+  organizationId,
+  state
+}) {
+  await dependencies.stateStore.save({
+    ...state,
+    lastUsedOrgId: organizationId
+  });
+}
 function addRegistryOperationCommand({
   program: program2,
   commandGroups,
@@ -10360,7 +10414,6 @@ function createDefaultDependencies() {
       accessTokenFilePath
     },
     refreshTokenStore: runtimeConfig.refreshTokenStoreKind === "file" ? createFileRefreshTokenStore(refreshTokenFilePath) : createKeytarRefreshTokenStore(runtimeConfig.keychainServiceName),
-    ensureLatestCliVersion: async () => getInstalledCliUpdateRequirement(selfUpdateOptions),
     settingsStore,
     selfUpdateCli: async () => selfUpdateInstalledCli(selfUpdateOptions),
     stateStore: createFileStateStore(runtimeConfig.stateFilePath)
@@ -10395,13 +10448,6 @@ ${formatOutputModesNote()}`
     }
     this.outputHelp();
   });
-  program2.hook("preAction", async (_command, actionCommand) => {
-    await enforceLatestCliVersionIfNeeded({
-      actionCommand,
-      dependencies,
-      program: program2
-    });
-  });
   const authCommand = configureCommandPresentation(
     new Command2("auth").description("Manage CLI authentication.")
   ).helpGroup("Workspace:").addHelpText(
@@ -10438,6 +10484,66 @@ ${formatExamples("Examples", [
     );
   });
   program2.addCommand(orgCommand);
+  const nangoCommand = configureCommandPresentation(
+    new Command2("nango").description(
+      "Inspect Nango integrations and org-scoped authentications."
+    )
+  ).helpGroup("Workspace:").addHelpText(
+    "after",
+    `
+${formatExamples("Examples", [
+      "mgcl nango integrations list --json",
+      "mgcl nango auths list --integration github --json"
+    ])}`
+  );
+  const nangoIntegrationsCommand = configureCommandPresentation(
+    new Command2("integrations").description("Work with Nango integrations.")
+  );
+  nangoIntegrationsCommand.command("list").description("List Nango integrations available in the current workspace.").addOption(
+    new Option2(
+      "--org <org>",
+      "Organization ID or exact organization name to use."
+    ).helpGroup("Shared options:")
+  ).action(async function() {
+    await handleNangoIntegrationsListCommand(
+      dependencies,
+      this.optsWithGlobals()
+    );
+  });
+  nangoCommand.addCommand(nangoIntegrationsCommand);
+  const nangoAuthsCommand = configureCommandPresentation(
+    new Command2("auths").alias("authentications").description("Work with org-scoped Nango authentications.")
+  );
+  nangoAuthsCommand.command("list").description(
+    "List org-scoped Nango authentications and their connection IDs."
+  ).addOption(
+    new Option2(
+      "--org <org>",
+      "Organization ID or exact organization name to use."
+    ).helpGroup("Shared options:")
+  ).addOption(
+    new Option2(
+      "--integration <integration>",
+      "Optional integration key to filter Nango authentications."
+    )
+  ).addOption(
+    new Option2(
+      "--connection-id <connectionId>",
+      "Optional connection ID to filter Nango authentications."
+    )
+  ).addHelpText(
+    "after",
+    `
+${formatExamples("Examples", [
+      "mgcl nango auths list --json",
+      "mgcl nango auths list --integration github --json",
+      "mgcl nango auths list --integration github --connection-id <id> --json"
+    ])}`
+  ).action(async function() {
+    await handleNangoAuthsListCommand(dependencies, this.optsWithGlobals());
+  });
+  nangoCommand.addCommand(nangoAuthsCommand);
+  program2.addCommand(nangoCommand);
   const updateCommand = configureCommandPresentation(
     new Command2("update").description(
       "Update mgcl to the latest published npm release."