Variables and Capacities

Variables and Capacities make dependencies explicit before an agent reaches blocked work. A Variable is information. A Capacity is an external ability available through one or more connectors.

Variables

Declare Variables at the Playbook root. A Variable can be text, long text, a number, a boolean, a file, a URL, a choice, or multiple choices.

const releaseCandidate = variable(
  "releaseCandidate",
  v.url({
    title: "Release candidate",
    purpose: "The preview or deployment the agent should evaluate.",
  }),
).resolution({
  mode: "human",
  freshness: "fresh_required",
  sources: ["run_value", "reference_url"],
});

Resolution policy answers three questions:

• mode: can Doku resolve the value automatically, or should a human provide it?
• freshness: may a previous value be reused, or must this Run receive a fresh value?
• sources: which provenance channels are acceptable?

Use .optional() when the Playbook still has a valid path without the value.

Capacities

A Capacity describes what the Playbook needs to do in an external system. It does not grant access by itself. Doku still resolves the available Connector Instance and enforces the caller's current authority.

import { all, capacity, connector } from "@doku/playbook-sdk";
import { connectorProducts, connectors } from "@doku/connector-sdk";

const deploymentAccess = capacity("deploymentAccess", {
  title: "Cloudflare deployment access",
  description: "Inspect and deploy the launch Worker.",
  connectors: connector(connectorProducts.cloudflare.developerPlatform, {
    actions: all(
      connectors.cloudflare.developerPlatform.workers.listScripts,
      connectors.cloudflare.developerPlatform.workers.deployModule,
      connectors.cloudflare.developerPlatform.workers.listDeployments,
    ),
  }),
});

Narrow action-level declarations are easier to review than product-wide access. If the Playbook supports alternative providers, use any(...). If it requires multiple connector products together, use all(...).

Authoring rules

• Do not hide required input inside Task instructions.
• Do not model connector-backed choices as arbitrary text when Doku can discover the resource.
• Do not request broad connector access “just in case.”
• Treat credentials, approvals, and unresolved user choices as blockers—not values an agent may invent.
• Keep optional paths truly optional through the entire task graph.