divedra-workflow-reference

name	divedra-workflow-reference
description	Use when helping developers integrate with divedra workflows programmatically. Applies to the divedra package API, createWorkflowExecutionClient, inspectWorkflow, executeWorkflow, resumeWorkflow, rerunWorkflow, getRuntimeSessionView, callWorkflowStep, executeGraphqlRequest, createGraphqlSchema, executeGraphqlDocument, GraphQL control-plane queries and mutations, divedra graphql, manager-session auth, and choosing between local library calls and remote GraphQL endpoint calls.
metadata	{"short-description":"Use divedra workflow APIs"}

Divedra Workflow Reference

Use this skill for developer-facing references and integrations. For end-user CLI operation, use divedra-workflow-run. For authoring workflow bundles, use divedra-workflow.

Choose The Integration Surface

• Use workflow usage --output json from the CLI when a tool-using LLM needs to choose among workflows by purpose, compact step overview, and callable contract.
• Use createWorkflowExecutionClient() when code should work locally or remotely with the same shape. If endpoint is present, it uses GraphQL; otherwise it uses the local library path.
• Use direct library functions such as inspectWorkflow(), executeWorkflow(), resumeWorkflow(), rerunWorkflow(), and getRuntimeSessionView() for in-process Node/Bun integration.
• Use executeGraphqlRequest() for low-level GraphQL HTTP calls.
• Use divedra graphql for shell-based GraphQL queries and manager/control-plane actions.
• Use createGraphqlSchema() or executeGraphqlDocument() for in-process GraphQL without HTTP.
• Use callWorkflowStep() only for local step-addressed debugging/integration; do not invent node-addressed aliases.

Read references/api-reference.md when the task needs concrete imports, GraphQL document examples, manager auth, endpoint behavior, or API selection tradeoffs.

Common Imports

import {
  createWorkflowExecutionClient,
  executeGraphqlRequest,
  executeWorkflow,
  getRuntimeSessionView,
  inspectWorkflow,
} from "divedra";

Unified Execution Client

Local library execution:

const client = createWorkflowExecutionClient({
  workflowName: "example-workflow",
  workflowRoot: "./examples",
  env: process.env,
});

const result = await client.execute({
  input: {
    humanInput: {
      request: "Run this workflow",
    },
  },
});

Remote GraphQL execution:

const client = createWorkflowExecutionClient({
  workflowName: "example-workflow",
  endpoint: "http://127.0.0.1:43173/graphql",
  authToken: process.env.DIVEDRA_MANAGER_AUTH_TOKEN,
  managerSessionId: process.env.DIVEDRA_MANAGER_SESSION_ID,
});

const result = await client.execute({
  runtimeVariables: {
    humanInput: {
      request: "Run this workflow",
    },
  },
  async: true,
});

Do not pass both input and runtimeVariables; they are aliases and the client rejects using both at once.

Direct Library Pattern

const inspection = await inspectWorkflow("example-workflow", {
  workflowRoot: "./examples",
  env: process.env,
});

const run = await executeWorkflow({
  workflowName: "example-workflow",
  workflowRoot: "./examples",
  env: process.env,
  runtimeVariables: {
    humanInput: {
      request: "Run this workflow",
    },
  },
});

const runtime = await getRuntimeSessionView(run.sessionId, {
  env: process.env,
});

GraphQL Request Pattern

const response = await executeGraphqlRequest({
  endpoint: "http://127.0.0.1:43173/graphql",
  document: `
    mutation ExecuteWorkflow($input: ExecuteWorkflowInput!) {
      executeWorkflow(input: $input) {
        workflowExecutionId
        sessionId
        status
        accepted
        exitCode
      }
    }
  `,
  variables: {
    input: {
      workflowName: "example-workflow",
      runtimeVariables: {
        humanInput: {
          request: "Run this workflow",
        },
      },
    },
  },
});

if (response.errors?.length) {
  throw new Error(response.errors.map((error) => error.message).join("; "));
}

GraphQL CLI Pattern

Workflow discovery before execution:

divedra workflow usage --workflow-definition-dir ./examples --output json

divedra graphql 'query { workflows(input: {}) }'

With variables:

divedra graphql '
  mutation ExecuteWorkflow($input: ExecuteWorkflowInput!) {
    executeWorkflow(input: $input) {
      sessionId
      status
    }
  }
' --variables @variables.json

Integration Rules

• Without --endpoint, the GraphQL CLI executes in-process against local project-scoped workflow/session storage.
• Endpoint resolution for remote CLI transport is --endpoint, then DIVEDRA_GRAPHQL_ENDPOINT.
• executeGraphqlRequest() sends standard { query, variables } JSON and returns { data, errors }.
• authToken becomes Authorization: Bearer <token>.
• managerSessionId becomes the manager-session header used by divedra GraphQL.
• Manager-scoped mutations require both manager session id and auth token.
• GraphQL file/image parameters must use data-root-relative paths, not host absolute paths.
• Attachment files must already exist; the current API does not provide an upload mutation.
• Remote GraphQL execution must not rely on local-only debug features such as --mock-scenario.