@lunnoa/client 2.5.0 → 3.0.0

package/dist/index.cjs

@@ -28,16 +28,21 @@ var LunnoaApiError = class extends Error {
   method;
   /** Path of the failed request (without the base URL). */
   path;
+  /** Present on definition-sync 409s when the server sends the current revision. */
+  currentRevision;
   constructor(args) {
     const detail = extractMessage(args.body);
+    const currentRevision = extractCurrentRevision(args.body);
+    const shown = [detail, currentRevision ? `currentRevision: ${currentRevision}` : void 0].filter(Boolean).join(" ");
     super(
-      `Lunnoa API request failed: ${args.method} ${args.path} \u2192 ${args.status}${detail ? ` (${detail})` : ""}`
+      `Lunnoa API request failed: ${args.method} ${args.path} \u2192 ${args.status}${shown ? ` (${shown})` : ""}`
     );
     this.name = "LunnoaApiError";
     this.status = args.status;
     this.body = args.body;
     this.method = args.method;
     this.path = args.path;
+    this.currentRevision = currentRevision;
   }
   /** True for 401 responses (missing, revoked, or expired credential). */
   get isUnauthorized() {
@@ -56,6 +61,11 @@ var LunnoaApiError = class extends Error {
     return this.status === 429;
   }
 };
+function extractCurrentRevision(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const revision = body.currentRevision;
+  return typeof revision === "string" ? revision : void 0;
+}
 function extractMessage(body) {
   if (body && typeof body === "object") {
     const record = body;
@@ -532,6 +542,139 @@ var ActionsResource = class {
   }
 };
 
+// src/define/files.ts
+var STEP_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+function hasFileAgentSignals(record) {
+  if (record.instructions && typeof record.instructions === "object") return true;
+  if (record.settings && typeof record.settings === "object") return true;
+  if ("workflows" in record || "agents" in record || "knowledge" in record || "variables" in record || "objects" in record || "objectTypes" in record || "mcpServers" in record || "a2aAgents" in record) {
+    return true;
+  }
+  return Array.isArray(record.tools) && record.tools.some(
+    (tool) => tool && typeof tool === "object" && !("kind" in tool) && !("use" in tool)
+  );
+}
+function isAgentFileInput(config) {
+  if (!config || typeof config !== "object") return false;
+  return hasFileAgentSignals(config);
+}
+function isAgentFileShape(config) {
+  if (!config || typeof config !== "object") return false;
+  return hasFileAgentSignals(config);
+}
+function acceptAgentFile(config) {
+  const slug = config.slug?.trim();
+  if (!slug) throw new Error("defineAgent requires slug");
+  const instructions = config.instructions;
+  const fileRef = instructions && typeof instructions === "object" && typeof instructions.file === "string" && instructions.file.trim().length > 0;
+  if (typeof instructions !== "string" && !fileRef) {
+    throw new Error("defineAgent requires instructions");
+  }
+  const copy = { ...config };
+  delete copy.$schema;
+  delete copy.kind;
+  return { ...copy, kind: "agent", slug, instructions };
+}
+function assertStepKeys(steps, seen) {
+  for (const step of steps ?? []) {
+    if (!step?.use?.id?.trim()) {
+      throw new Error("workflow step requires use.id");
+    }
+    if (step.key !== void 0) {
+      if (!STEP_KEY_PATTERN.test(step.key) || step.key === "trigger") {
+        throw new Error(
+          `Step key "${step.key}" must start with a letter, use letters, digits, - or _, and not be "trigger".`
+        );
+      }
+      if (seen.has(step.key)) {
+        throw new Error(`Step key "${step.key}" is used twice.`);
+      }
+      seen.add(step.key);
+    }
+    for (const path of step.paths ?? []) {
+      assertStepKeys(path.steps ?? [], seen);
+    }
+  }
+}
+function acceptWorkflowStepsFile(config) {
+  const slug = config.slug?.trim();
+  if (!slug) throw new Error("defineWorkflow requires slug");
+  if (!config.steps?.length) {
+    throw new Error("defineWorkflow requires at least one step");
+  }
+  if (config.trigger && !config.trigger.id?.trim()) {
+    throw new Error("defineWorkflow trigger requires id");
+  }
+  assertStepKeys(config.steps, /* @__PURE__ */ new Set());
+  const copy = { ...config };
+  delete copy.$schema;
+  delete copy.kind;
+  return {
+    ...copy,
+    kind: "workflow",
+    format: "steps",
+    slug
+  };
+}
+function acceptWorkflowGraphFile(config) {
+  const slug = config.slug?.trim();
+  if (!slug) throw new Error("defineWorkflow requires slug");
+  if (!Array.isArray(config.nodes) || config.nodes.length === 0) {
+    throw new Error("defineWorkflow graph requires nodes");
+  }
+  const keys = /* @__PURE__ */ new Set();
+  let triggers = 0;
+  for (const node of config.nodes) {
+    if (!node?.key || typeof node.key !== "string") {
+      throw new Error("graph node requires key");
+    }
+    if (!STEP_KEY_PATTERN.test(node.key)) {
+      throw new Error(
+        `Node key "${node.key}" must start with a letter, use letters, digits, - or _, and not be empty.`
+      );
+    }
+    if (keys.has(node.key)) {
+      throw new Error(`Node key "${node.key}" is used twice.`);
+    }
+    keys.add(node.key);
+    if (node.nodeType === "trigger") triggers += 1;
+  }
+  if (triggers !== 1) {
+    throw new Error("defineWorkflow graph requires exactly one trigger");
+  }
+  for (const edge of config.edges ?? []) {
+    if (!keys.has(edge?.source) || !keys.has(edge?.target)) {
+      throw new Error(
+        `Edge from "${edge?.source ?? ""}" to "${edge?.target ?? ""}" references an unknown key.`
+      );
+    }
+  }
+  const copy = { ...config };
+  delete copy.$schema;
+  delete copy.kind;
+  return {
+    ...copy,
+    kind: "workflow",
+    format: "graph",
+    slug,
+    edges: config.edges ?? []
+  };
+}
+function isWorkflowGraphInput(config) {
+  return !!config && typeof config === "object" && config.format === "graph";
+}
+function isWorkflowStepsFile(config) {
+  if (!config || typeof config !== "object") return false;
+  const record = config;
+  if (record.format === "steps") return true;
+  if (record.trigger && typeof record.trigger === "object" && record.trigger.kind !== "trigger" && typeof record.trigger.id === "string") {
+    return true;
+  }
+  return Array.isArray(record.steps) && record.steps.some(
+    (step) => step && typeof step === "object" && step.use && step.use?.kind !== "action"
+  );
+}
+
 // src/define/index.ts
 var DEFINE_KINDS = {
   connection: "connection",
@@ -601,7 +744,7 @@ function defineTrigger(config) {
 }
 var MANUAL_TRIGGER_ID = "flow-control_trigger_manual";
 var TRIGGER_KEY = "trigger";
-var STEP_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+var STEP_KEY_PATTERN2 = /^[A-Za-z][A-Za-z0-9_-]*$/;
 var STEP_REF_PATTERN = /={{step:([^}]*)}}/g;
 function refString(key, path) {
   const parts = [key, ...path.map(String)];
@@ -641,7 +784,7 @@ var SINGLE_REF_PATTERN = /^={{step:[^}]*}}$/;
 function collectKeys(steps, seen) {
   for (const step of steps) {
     if (step.key !== void 0) {
-      if (!STEP_KEY_PATTERN.test(step.key) || step.key === TRIGGER_KEY) {
+      if (!STEP_KEY_PATTERN2.test(step.key) || step.key === TRIGGER_KEY) {
         throw new Error(
           `Step key "${step.key}" must start with a letter, use letters, digits, - or _, and not be "${TRIGGER_KEY}".`
         );
@@ -725,29 +868,43 @@ function assertStepRefs(config) {
   checkChain(config.steps, /* @__PURE__ */ new Set([TRIGGER_KEY]));
 }
 function defineWorkflow(config) {
-  if (!config.slug?.trim()) {
+  const record = config;
+  if (isWorkflowGraphInput(config) || Array.isArray(record.nodes) && !Array.isArray(record.steps)) {
+    return acceptWorkflowGraphFile(config);
+  }
+  if (isWorkflowStepsFile(config)) {
+    return acceptWorkflowStepsFile(config);
+  }
+  const authored = { ...config };
+  delete authored.$schema;
+  if (!authored.slug?.trim()) {
     throw new Error("defineWorkflow requires slug");
   }
-  if (!config.steps?.length) {
+  if (!authored.steps?.length) {
     throw new Error("defineWorkflow requires at least one step");
   }
-  if (config.trigger) {
-    assertTriggerConfig(config.trigger);
+  if (authored.trigger) {
+    assertTriggerConfig(authored.trigger);
   }
-  assertStepRefs(config);
-  return { kind: DEFINE_KINDS.workflow, ...config };
+  assertStepRefs(authored);
+  return { kind: DEFINE_KINDS.workflow, ...authored };
 }
 function defineAgent(config) {
-  if (!config.slug?.trim()) {
+  if (isAgentFileInput(config)) {
+    return acceptAgentFile(config);
+  }
+  const authored = { ...config };
+  delete authored.$schema;
+  if (!authored.slug?.trim()) {
     throw new Error("defineAgent requires slug");
   }
-  if (!config.model?.trim()) {
+  if (!authored.model?.trim()) {
     throw new Error("defineAgent requires model");
   }
-  if (config.instructions == null) {
+  if (authored.instructions == null) {
     throw new Error("defineAgent requires instructions");
   }
-  return { kind: DEFINE_KINDS.agent, ...config };
+  return { kind: DEFINE_KINDS.agent, ...authored };
 }
 function defineEntityType(config) {
   if (!config.slug?.trim()) {
@@ -862,10 +1019,24 @@ function unwrapTool(tool) {
   }
   return tool;
 }
+function syncFields(options) {
+  return {
+    ...options?.baseRevision ? { baseRevision: options.baseRevision } : {},
+    ...options?.force ? { force: true } : {}
+  };
+}
+function idsOf(links) {
+  if (!links) return void 0;
+  return links.map((link) => link.id);
+}
 function agentDefinitionToUpsert(def, options) {
+  if (isAgentFileShape(def)) {
+    return fileAgentToUpsert(def, options);
+  }
   const tools = [];
   const workflowIds = [...options?.workflowIds ?? []];
-  for (const tool of def.tools ?? []) {
+  const authored = def;
+  for (const tool of authored.tools ?? []) {
     const unwrapped = unwrapTool(tool);
     if (unwrapped.kind === DEFINE_KINDS.workflow) {
       continue;
@@ -881,17 +1052,65 @@ function agentDefinitionToUpsert(def, options) {
       });
     }
   }
+  return {
+    slug: authored.slug,
+    name: authored.name,
+    description: authored.description,
+    instructions: authored.instructions,
+    model: authored.model,
+    aiConnectionId: authored.aiConnection?.id,
+    connectionIds: authored.connections?.map((c) => c.id).filter((id) => Boolean(id)),
+    workflowIds: workflowIds.length ? workflowIds : void 0,
+    tools,
+    codeSource: options?.codeSource ?? "generated",
+    ...syncFields(options)
+  };
+}
+function fileAgentToUpsert(def, options) {
+  if (typeof def.instructions !== "string") {
+    throw new Error(
+      "Agent instructions are still a file reference. The CLI resolves these before push."
+    );
+  }
+  const tools = [];
+  for (const tool of def.tools ?? []) {
+    const action = {
+      kind: DEFINE_KINDS.action,
+      id: tool.id,
+      appId: tool.appId,
+      connection: tool.connection?.id ? { kind: DEFINE_KINDS.connection, id: tool.connection.id } : void 0
+    };
+    tools.push({
+      key: tool.key,
+      appId: resolveActionAppId(action),
+      actionId: resolveActionId(action),
+      connectionId: tool.connection?.id,
+      name: tool.name,
+      description: tool.description,
+      input: tool.input
+    });
+  }
   return {
     slug: def.slug,
     name: def.name,
-    description: def.description,
+    // A file is the whole definition. Omitted description and model are empty.
+    description: def.description ?? null,
     instructions: def.instructions,
-    model: def.model,
+    model: def.model ?? null,
     aiConnectionId: def.aiConnection?.id,
-    connectionIds: def.connections?.map((c) => c.id).filter((id) => Boolean(id)),
-    workflowIds: workflowIds.length ? workflowIds : void 0,
-    tools,
-    managedByCode: true
+    ...def.settings ? { settings: def.settings } : {},
+    ...def.tools ? { tools } : {},
+    ...def.workflows ? { workflows: def.workflows } : {},
+    ...def.agents ? { agents: def.agents } : {},
+    ...def.connections ? { connectionIds: idsOf(def.connections) } : {},
+    ...def.knowledge ? { knowledgeIds: idsOf(def.knowledge) } : {},
+    ...def.variables ? { variableIds: idsOf(def.variables) } : {},
+    ...def.objects ? { objectIds: idsOf(def.objects) } : {},
+    ...def.objectTypes ? { objectTypeIds: idsOf(def.objectTypes) } : {},
+    ...def.mcpServers ? { mcpServers: def.mcpServers } : {},
+    ...def.a2aAgents ? { a2aAgentIds: idsOf(def.a2aAgents) } : {},
+    codeSource: "synced",
+    ...syncFields(options)
   };
 }
 var AgentsResource = class {
@@ -911,15 +1130,22 @@ var AgentsResource = class {
       query: serializeListQuery(options)
     });
   }
+  /** Exported definition for `lunnoa/agents/<slug>.json`. */
+  getDefinition(slug) {
+    return this.http.get(
+      `/api/agents/slug/${encodeURIComponent(slug)}/definition`
+    );
+  }
   /**
    * Upsert an agent by slug inside the workspace on the API key.
    * Prefer the CLI (`npx @lunnoa/client agents deploy`) for happy-path deploy.
    */
   upsertBySlug(body, options) {
     const payload = "kind" in body && body.kind === "agent" ? agentDefinitionToUpsert(body, options) : body;
-    return this.http.post("/api/agents/upsert", {
-      body: payload
-    });
+    return this.http.post(
+      "/api/agents/upsert",
+      { body: payload }
+    );
   }
 };
 
@@ -2043,6 +2269,11 @@ function stepFromDefinition(step) {
 }
 function normalizeStartRunInput(input) {
   if (isWorkflowDefinition(input)) {
+    if ("format" in input && input.format === "graph") {
+      throw new Error(
+        "runs.start runs straight lines only. Push the graph workflow, then execute it."
+      );
+    }
     return {
       steps: input.steps.map(stepFromDefinition),
       name: input.name ?? input.slug
@@ -2234,6 +2465,18 @@ var WorkflowAppsResource = class {
   }
 };
 
+// src/resources/code-sync.ts
+var CodeSyncResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Workspace id and whether synced resources are locked in the UI. */
+  context() {
+    return this.http.get("/api/code-sync/context");
+  }
+};
+
 // src/resources/workflows.ts
 function triggerToUpsertInput(trigger) {
   return {
@@ -2246,8 +2489,38 @@ function triggerToUpsertInput(trigger) {
     ...trigger.description ? { description: trigger.description } : {}
   };
 }
+function asAction(use) {
+  if (use && typeof use === "object" && "kind" in use && use.kind === DEFINE_KINDS.action) {
+    return use;
+  }
+  const fileUse = use;
+  return {
+    kind: DEFINE_KINDS.action,
+    id: fileUse.id,
+    appId: fileUse.appId,
+    connection: fileUse.connection?.id ? { kind: DEFINE_KINDS.connection, id: fileUse.connection.id } : void 0
+  };
+}
+function asTrigger(trigger) {
+  if ("kind" in trigger && trigger.kind === DEFINE_KINDS.trigger) {
+    return trigger;
+  }
+  const fileTrigger = trigger;
+  return {
+    kind: DEFINE_KINDS.trigger,
+    id: fileTrigger.id,
+    appId: fileTrigger.appId,
+    connection: fileTrigger.connection?.id ? { kind: DEFINE_KINDS.connection, id: fileTrigger.connection.id } : void 0,
+    input: fileTrigger.input,
+    inputs: fileTrigger.inputs,
+    name: fileTrigger.name,
+    description: fileTrigger.description
+  };
+}
 function stepToUpsertInput(step) {
-  const use = step.use;
+  const use = asAction(step.use);
+  const retry = "retrySettings" in step ? step.retrySettings : void 0;
+  const continueOnFailure = "continueOnFailure" in step ? step.continueOnFailure : void 0;
   return {
     ...step.key ? { key: step.key } : {},
     appId: resolveActionAppId(use),
@@ -2258,25 +2531,60 @@ function stepToUpsertInput(step) {
       ...step.input ?? {}
     },
     name: step.name ?? use.name,
-    description: use.description,
+    description: step.description ?? use.description,
+    ...retry ? { retrySettings: retry } : {},
+    ...continueOnFailure ? { continueOnFailure } : {},
     ...step.paths?.length ? {
       paths: step.paths.map((path) => ({
         label: path.label,
         ...path.when ? { when: path.when } : {},
-        steps: path.steps.map(stepToUpsertInput)
+        steps: path.steps.map(
+          (nested) => stepToUpsertInput(nested)
+        )
       }))
     } : {}
   };
 }
-function workflowDefinitionToUpsert(def) {
+function syncFields2(options) {
   return {
-    slug: def.slug,
-    name: def.name,
-    description: def.description,
-    isActive: def.isActive,
-    ...def.trigger ? { trigger: triggerToUpsertInput(def.trigger) } : {},
-    managedByCode: true,
-    steps: def.steps.map(stepToUpsertInput)
+    ...options?.baseRevision ? { baseRevision: options.baseRevision } : {},
+    ...options?.force ? { force: true } : {}
+  };
+}
+function workflowDefinitionToUpsert(def, options) {
+  if ("format" in def && def.format === "graph") {
+    return {
+      slug: def.slug,
+      name: def.name,
+      // A file is the whole definition: an omitted description is empty, not "leave it".
+      description: def.description ?? null,
+      codeSource: "synced",
+      graph: { nodes: def.nodes, edges: def.edges ?? [] },
+      ...syncFields2(options)
+    };
+  }
+  if ("format" in def && def.format === "steps") {
+    const file = def;
+    return {
+      slug: file.slug,
+      name: file.name,
+      description: file.description ?? null,
+      ...file.trigger ? { trigger: triggerToUpsertInput(asTrigger(file.trigger)) } : {},
+      codeSource: "synced",
+      steps: file.steps.map((step) => stepToUpsertInput(step)),
+      ...syncFields2(options)
+    };
+  }
+  const authored = def;
+  return {
+    slug: authored.slug,
+    name: authored.name,
+    description: authored.description,
+    isActive: authored.isActive,
+    ...authored.trigger ? { trigger: triggerToUpsertInput(authored.trigger) } : {},
+    codeSource: options?.codeSource ?? "generated",
+    ...syncFields2(options),
+    steps: authored.steps.map((step) => stepToUpsertInput(step))
   };
 }
 var WorkflowsResource = class {
@@ -2301,15 +2609,22 @@ var WorkflowsResource = class {
       query: serializeListQuery(options)
     });
   }
+  /** Exported definition for `lunnoa/workflows/<slug>.json`. */
+  getDefinition(slug) {
+    return this.http.get(
+      `/api/workflows/slug/${encodeURIComponent(slug)}/definition`
+    );
+  }
   /**
    * Upsert a workflow by slug inside the workspace on the API key.
    * Prefer the CLI (`npx @lunnoa/client workflows deploy`) for happy-path deploy.
    */
-  upsertBySlug(body) {
-    const payload = "kind" in body && body.kind === "workflow" ? workflowDefinitionToUpsert(body) : body;
-    return this.http.post("/api/workflows/upsert", {
-      body: payload
-    });
+  upsertBySlug(body, options) {
+    const payload = "kind" in body && body.kind === "workflow" ? workflowDefinitionToUpsert(body, options) : body;
+    return this.http.post(
+      "/api/workflows/upsert",
+      { body: payload }
+    );
   }
   /**
    * Starts a new execution of the workflow with the given trigger inputs.
@@ -2375,6 +2690,8 @@ var LunnoaClient = class {
   aiConnections;
   workflowApps;
   discovery;
+  /** Workspace id for the definitions lock, and the code-sync lock flag. */
+  codeSync;
   constructor(options) {
     this.http = new HttpClient(options);
     this.auth = new AuthResource(this.http, this.http.tokenStore);
@@ -2398,6 +2715,7 @@ var LunnoaClient = class {
     this.connections = new ConnectionsResource(this.http);
     this.aiConnections = new AiConnectionsResource(this.http);
     this.discovery = new DiscoveryResource(this.http);
+    this.codeSync = new CodeSyncResource(this.http);
   }
 };
 
@@ -2481,6 +2799,7 @@ exports.AgentsResource = AgentsResource;
 exports.AiConnectionsResource = AiConnectionsResource;
 exports.ApprovalsResource = ApprovalsResource;
 exports.AuthResource = AuthResource;
+exports.CodeSyncResource = CodeSyncResource;
 exports.ConnectionsResource = ConnectionsResource;
 exports.DEFINE_KINDS = DEFINE_KINDS;
 exports.DiscoveryResource = DiscoveryResource;
@@ -2517,6 +2836,7 @@ exports.defineEntityType = defineEntityType;
 exports.defineTrigger = defineTrigger;
 exports.defineWorkflow = defineWorkflow;
 exports.entityTypeDefinitionToUpsert = entityTypeDefinitionToUpsert;
+exports.isAgentFileShape = isAgentFileShape;
 exports.isBrowserEnvironment = isBrowserEnvironment;
 exports.isLoginRequires2FA = isLoginRequires2FA;
 exports.iterateOffset = iterateOffset;