Operator Tooling API

The Operator Tooling API provides high-level helpers for the most common DevOps CLI tools — Docker, kubectl, Helm, Terraform, and more — as well as primitives for building and executing multi-step scoped workflows. All execution goes through the FDO host’s capability enforcement layer.

Import

import {
  // Operator tool presets
  getOperatorToolPreset,
  listOperatorToolPresets,
  createOperatorToolCapabilityPreset,
  createOperatorToolActionRequest,
  requestOperatorTool,

  // Generic scoped process execution
  createScopedProcessExecActionRequest,
  requestScopedProcessExec,

  // Workflow helpers
  createScopedWorkflowRequest,
  requestScopedWorkflow,

  // Workflow diagnostics
  summarizeWorkflowResult,
  getFailedWorkflowSteps,
  createWorkflowFailureDiagnostic,
} from "@anikitenko/fdo-sdk";

Types

`OperatorToolPresetId`

The 14 built-in operator tool preset identifiers:

type OperatorToolPresetId =
  | "docker-cli"
  | "kubectl"
  | "helm"
  | "terraform"
  | "ansible"
  | "aws-cli"
  | "gcloud"
  | "azure-cli"
  | "podman"
  | "kustomize"
  | "gh"
  | "git"
  | "vault"
  | "nomad";

`OperatorToolPresetDefinition`

The full definition of an operator tool preset, returned by getOperatorToolPreset and listOperatorToolPresets:

type OperatorToolPresetDefinition = {
  id: OperatorToolPresetId;
  label: string;
  description: string;
  scopeId: string;
  capabilities: ["system.process.exec", ProcessScopeCapability];
  suggestedCommands: string[];
  typicalUseCases: string[];
};

Field	Description
`id`	Preset identifier
`label`	Human-readable name (e.g. `"Docker CLI"`)
`description`	What the preset enables
`scopeId`	The scope id string used in capability and request building
`capabilities`	The exact `[PluginCapability, PluginCapability]` pair to declare in `PluginInitRequest`
`suggestedCommands`	CLI command names this preset targets
`typicalUseCases`	Common plugin patterns for this tool

`ScopedWorkflowRunActionRequest`

type ScopedWorkflowRunActionRequest = {
  action: "system.workflow.run";
  payload: {
    scope: string;
    kind: "process-sequence";
    title: string;
    summary?: string;
    dryRun?: boolean;
    steps: ScopedWorkflowProcessStep[];
    confirmation?: ScopedWorkflowConfirmation;
  };
};

`ScopedWorkflowProcessStep`

Defines a single step within a process-sequence workflow:

type ScopedWorkflowProcessStep = {
  id: string;
  title: string;
  phase?: "inspect" | "preview" | "mutate" | "apply" | "cleanup";
  command: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
  timeoutMs?: number;
  input?: string;
  encoding?: "utf8" | "base64";
  reason?: string;
  onError?: "abort" | "continue";
};

`ScopedWorkflowResult`

Returned inside a PrivilegedActionSuccessResponse when a workflow completes:

type ScopedWorkflowResult = {
  workflowId: string;
  scope: string;
  kind: "process-sequence";
  status: "completed" | "partial" | "failed";
  summary: {
    totalSteps: number;
    completedSteps: number;
    failedSteps: number;
    skippedSteps: number;
  };
  steps: ScopedWorkflowStepResult[];
};

`ScopedWorkflowStepResult`

type ScopedWorkflowStepResult = {
  stepId: string;
  title: string;
  status: "ok" | "error" | "skipped";
  correlationId?: string;
  result?: {
    command: string;
    args: string[];
    cwd?: string;
    exitCode?: number | null;
    stdout?: string;
    stderr?: string;
    durationMs?: number;
    dryRun?: boolean;
  };
  error?: string;
  code?: string;
};

Operator tool presets

`getOperatorToolPreset`

Returns the full OperatorToolPresetDefinition for a given preset id. Use the capabilities field to populate your PluginInitRequest.

getOperatorToolPreset(presetId: OperatorToolPresetId): OperatorToolPresetDefinition

const preset = getOperatorToolPreset("kubectl");
// {
//   id: "kubectl",
//   label: "kubectl",
//   scopeId: "kubectl",
//   capabilities: ["system.process.exec", "system.process.scope.kubectl"],
//   suggestedCommands: ["kubectl"],
//   typicalUseCases: ["Cluster dashboards", "Resource inspection", "Namespace operations"],
//   ...
// }

`listOperatorToolPresets`

Returns all 14 preset definitions sorted alphabetically by id.

listOperatorToolPresets(): OperatorToolPresetDefinition[]

const presets = listOperatorToolPresets();
presets.forEach(p => console.log(p.id, p.label));

`createOperatorToolCapabilityPreset`

Returns just the capabilities array for a given preset — a convenience shorthand for populating PluginInitRequest.capabilities.

createOperatorToolCapabilityPreset(presetId: OperatorToolPresetId): PluginCapability[]

const caps = createOperatorToolCapabilityPreset("docker-cli");
// → ["system.process.exec", "system.process.scope.docker-cli"]

`createOperatorToolActionRequest`

Builds a validated ProcessExecActionRequest for a specific preset. The preset’s scopeId is injected automatically.

createOperatorToolActionRequest(
  presetId: OperatorToolPresetId,
  payload: ProcessExecActionPayloadInput
): ProcessExecActionRequest

ProcessExecActionPayloadInput is the ProcessExecActionRequest["payload"] shape without the scope field — you supply everything except the scope.

const req = createOperatorToolActionRequest("kubectl", {
  command: "kubectl",
  args: ["get", "pods", "-n", "default"],
  timeoutMs: 10000,
});

`requestOperatorTool`

The one-call convenience for executing an operator tool. Builds the request, dispatches it through the iframe bridge, and returns the response promise.

requestOperatorTool<TResult = unknown>(
  presetId: OperatorToolPresetId,
  payload: ProcessExecActionPayloadInput,
  options?: RequestPrivilegedActionOptions
): Promise<PrivilegedActionResponse<TResult>>

const response = await requestOperatorTool("kubectl", {
  command: "kubectl",
  args: ["get", "nodes", "-o", "json"],
  timeoutMs: 15000,
});

if (response.ok) {
  console.log(response.result);
} else {
  console.error(response.error);
}

Generic scoped process execution

Use these when you need to run a process under a custom scope that does not match any built-in preset.

`createScopedProcessExecActionRequest`

Builds a ProcessExecActionRequest with an explicit scopeId.

createScopedProcessExecActionRequest(
  scopeId: string,
  payload: ProcessExecActionPayloadInput
): ProcessExecActionRequest

const req = createScopedProcessExecActionRequest("my-custom-tool", {
  command: "/usr/local/bin/my-tool",
  args: ["--flag", "value"],
});

`requestScopedProcessExec`

Dispatches a scoped process execution request and returns the response promise. Auto-prefixes the correlation id with scopeId.

requestScopedProcessExec<TResult = unknown>(
  scopeId: string,
  payload: ProcessExecActionPayloadInput,
  options?: RequestPrivilegedActionOptions
): Promise<PrivilegedActionResponse<TResult>>

Workflow helpers

`createScopedWorkflowRequest`

Builds a ScopedWorkflowRunActionRequest for a multi-step process-sequence workflow.

createScopedWorkflowRequest(
  scopeId: string,
  payload: ScopedWorkflowPayloadInput
): ScopedWorkflowRunActionRequest

ScopedWorkflowPayloadInput is the workflow payload shape without the scope field.

const req = createScopedWorkflowRequest("kubectl", {
  kind: "process-sequence",
  title: "Restart deployment",
  steps: [
    {
      id: "inspect",
      title: "Check deployment status",
      phase: "inspect",
      command: "kubectl",
      args: ["get", "deploy", "my-app", "-n", "default"],
    },
    {
      id: "restart",
      title: "Restart deployment",
      phase: "apply",
      command: "kubectl",
      args: ["rollout", "restart", "deploy/my-app", "-n", "default"],
      onError: "abort",
    },
  ],
});

`requestScopedWorkflow`

Dispatches a workflow request and returns Promise<PrivilegedActionResponse<ScopedWorkflowResult>>.

requestScopedWorkflow(
  scopeId: string,
  payload: ScopedWorkflowPayloadInput,
  options?: RequestPrivilegedActionOptions
): Promise<PrivilegedActionResponse<ScopedWorkflowResult>>

const response = await requestScopedWorkflow("kubectl", {
  kind: "process-sequence",
  title: "Restart deployment",
  steps: [ /* ... */ ],
});

Workflow diagnostics

`summarizeWorkflowResult`

Extracts a flat summary object from a ScopedWorkflowResult. Useful for logging or building status UI.

summarizeWorkflowResult(result: ScopedWorkflowResult): {
  workflowId: string;
  scope: string;
  kind: ScopedWorkflowResult["kind"];
  status: ScopedWorkflowResult["status"];
  totalSteps: number;
  completedSteps: number;
  failedSteps: number;
  skippedSteps: number;
}

const summary = summarizeWorkflowResult(result);
console.log(`${summary.completedSteps}/${summary.totalSteps} steps completed`);

`getFailedWorkflowSteps`

Filters result.steps to only those with status === "error".

getFailedWorkflowSteps(result: ScopedWorkflowResult): ScopedWorkflowStepResult[]

const failed = getFailedWorkflowSteps(result);
failed.forEach(step => console.error(`Step "${step.title}" failed: ${step.error}`));

`createWorkflowFailureDiagnostic`

Returns a structured WorkflowFailureDiagnostic object when there are failed steps, or null when all steps succeeded. Includes details about the first failed step and a remediation hint.

createWorkflowFailureDiagnostic(result: ScopedWorkflowResult): WorkflowFailureDiagnostic | null

type WorkflowFailureDiagnostic = {
  workflowId: string;
  scope: string;
  status: ScopedWorkflowResult["status"];
  failedStepIds: string[];
  failedStepTitles: string[];
  firstFailedStep?: {
    stepId: string;
    title: string;
    correlationId?: string;
    error?: string;
    code?: string;
  };
  remediation: string;
};

const diag = createWorkflowFailureDiagnostic(result);
if (diag) {
  console.error(`Workflow failed at step: ${diag.firstFailedStep?.title}`);
  console.error(diag.remediation);
}

End-to-end example: kubectl preset

import {
  createOperatorToolCapabilityPreset,
  requestOperatorTool,
  isPrivilegedActionSuccessResponse,
} from "@anikitenko/fdo-sdk";

// 1. Declare capabilities in plugin init
const capabilities = createOperatorToolCapabilityPreset("kubectl");

// 2. Execute a kubectl command in a handler
async function listPods(namespace: string) {
  const response = await requestOperatorTool("kubectl", {
    command: "kubectl",
    args: ["get", "pods", "-n", namespace, "-o", "json"],
    timeoutMs: 15000,
  });

  if (isPrivilegedActionSuccessResponse(response)) {
    return response.result;
  }
  throw new Error(response.error);
}

End-to-end example: multi-step workflow

import {
  createWorkflowCapabilityBundle,
  requestScopedWorkflow,
  summarizeWorkflowResult,
  createWorkflowFailureDiagnostic,
  unwrapPrivilegedActionResponse,
} from "@anikitenko/fdo-sdk";

// 1. Declare capabilities
const capabilities = createWorkflowCapabilityBundle("kubectl");

// 2. Run a workflow
async function restartDeployment(name: string, namespace: string) {
  const response = await requestScopedWorkflow("kubectl", {
    kind: "process-sequence",
    title: `Restart ${name}`,
    steps: [
      {
        id: "check",
        title: "Check current status",
        phase: "inspect",
        command: "kubectl",
        args: ["get", "deploy", name, "-n", namespace],
        onError: "abort",
      },
      {
        id: "restart",
        title: "Rollout restart",
        phase: "apply",
        command: "kubectl",
        args: ["rollout", "restart", `deploy/${name}`, "-n", namespace],
        onError: "abort",
      },
      {
        id: "wait",
        title: "Wait for rollout",
        phase: "cleanup",
        command: "kubectl",
        args: ["rollout", "status", `deploy/${name}`, "-n", namespace, "--timeout=60s"],
      },
    ],
  });

  const result = unwrapPrivilegedActionResponse(response);
  if (!result) throw new Error("No result returned");

  const summary = summarizeWorkflowResult(result);
  console.log(`${summary.completedSteps}/${summary.totalSteps} steps completed (${summary.status})`);

  const diag = createWorkflowFailureDiagnostic(result);
  if (diag) {
    throw new Error(`Workflow failed: ${diag.firstFailedStep?.error ?? "unknown error"}`);
  }

  return result;
}

Use onError: "abort" on critical steps to stop the workflow immediately on failure. Use onError: "continue" (the default) for non-critical steps like cleanup where partial success is acceptable.

Built-in preset reference

Preset ID	Label	Scope ID	Suggested Commands
`docker-cli`	Docker CLI	`docker-cli`	`docker`, `docker compose`
`kubectl`	kubectl	`kubectl`	`kubectl`
`helm`	Helm	`helm`	`helm`
`terraform`	Terraform	`terraform`	`terraform`
`ansible`	Ansible	`ansible`	`ansible`, `ansible-playbook`
`aws-cli`	AWS CLI	`aws-cli`	`aws`
`gcloud`	Google Cloud CLI	`gcloud`	`gcloud`
`azure-cli`	Azure CLI	`azure-cli`	`az`
`podman`	Podman	`podman`	`podman`
`kustomize`	Kustomize	`kustomize`	`kustomize`, `kubectl kustomize`
`gh`	GitHub CLI	`gh`	`gh`
`git`	Git	`git`	`git`
`vault`	Vault	`vault`	`vault`
`nomad`	Nomad	`nomad`	`nomad`

Core API

DOM Helpers

Privileged Actions

Operator Tooling API

Import

Types

`OperatorToolPresetId`

`OperatorToolPresetDefinition`

`ScopedWorkflowRunActionRequest`

`ScopedWorkflowProcessStep`

`ScopedWorkflowResult`

`ScopedWorkflowStepResult`

Operator tool presets

`getOperatorToolPreset`

`listOperatorToolPresets`

`createOperatorToolCapabilityPreset`

`createOperatorToolActionRequest`

`requestOperatorTool`

Generic scoped process execution

`createScopedProcessExecActionRequest`

`requestScopedProcessExec`

Workflow helpers

`createScopedWorkflowRequest`

`requestScopedWorkflow`

Workflow diagnostics

`summarizeWorkflowResult`

`getFailedWorkflowSteps`

`createWorkflowFailureDiagnostic`

End-to-end example: kubectl preset

End-to-end example: multi-step workflow

Built-in preset reference

Core API

DOM Helpers

Privileged Actions

​Import

​Types

​OperatorToolPresetId

​OperatorToolPresetDefinition

​ScopedWorkflowRunActionRequest

​ScopedWorkflowProcessStep

​ScopedWorkflowResult

​ScopedWorkflowStepResult

​Operator tool presets

​getOperatorToolPreset

​listOperatorToolPresets

​createOperatorToolCapabilityPreset

​createOperatorToolActionRequest

​requestOperatorTool

​Generic scoped process execution

​createScopedProcessExecActionRequest

​requestScopedProcessExec

​Workflow helpers

​createScopedWorkflowRequest

​requestScopedWorkflow

​Workflow diagnostics

​summarizeWorkflowResult

​getFailedWorkflowSteps

​createWorkflowFailureDiagnostic

​End-to-end example: kubectl preset

​End-to-end example: multi-step workflow

​Built-in preset reference

Import

Types

`OperatorToolPresetId`

`OperatorToolPresetDefinition`

`ScopedWorkflowRunActionRequest`

`ScopedWorkflowProcessStep`

`ScopedWorkflowResult`

`ScopedWorkflowStepResult`

Operator tool presets

`getOperatorToolPreset`

`listOperatorToolPresets`

`createOperatorToolCapabilityPreset`

`createOperatorToolActionRequest`

`requestOperatorTool`

Generic scoped process execution

`createScopedProcessExecActionRequest`

`requestScopedProcessExec`

Workflow helpers

`createScopedWorkflowRequest`

`requestScopedWorkflow`

Workflow diagnostics

`summarizeWorkflowResult`

`getFailedWorkflowSteps`

`createWorkflowFailureDiagnostic`

End-to-end example: kubectl preset

End-to-end example: multi-step workflow

Built-in preset reference