Dify
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
The Dynamo Dify tool plugin gives Dify agents and workflows a capped, revocable slice of one Dynamo budget per run. Paid HTTP or AI steps run under that slice's caps, and Dify gets a typed refusal at the cap. It has three tools:
- Open run allowance (delegator credential) opens a capped child
allowance for this run under your delegated stream, and returns its stream_id.
- Attach (hook or delegator credential) reads an allowance's remaining
headroom.
- Pay step (hook credential) reserves the step's units first, calls your
endpoint, and confirms the units only when the step succeeds. A failed step is released, so it costs nothing.
The plugin is not submitted to the Dify Marketplace.
Credentials
The provider takes the core URL and one scoped credential, never the owner token. The budget owner mints the credentials with POST /owner/v1/scoped-credentials: a delegator credential ({"kind": "delegator", "streamId": …}) opens run allowances, and a hook credential ({"kind": "hook", "budgetId": …}) pays steps.
Package it
The README documents packaging the plugin with the Dify plugin CLI:
cd packages/plugin-dify
pwd
dify plugin package . -o dynamo.difypkg
make test-dify-plugin from the repository root packages the plugin with a pinned Dify plugin CLI (checking its checksum first), then runs the packaged plugin on Dify's own stdio runtime protocol against a local core.
Installing an unsigned .difypkg into a self-hosted Dify needs a signature or FORCE_VERIFYING_SIGNATURE=false. The README does not document the rest of the install into Dify.
Wrap a workflow run in a budget
Open a run allowance with Open run allowance, then pass its stream_id to each Pay step. An allowance accrues at its rate from the second it opens, and a pay step in that same second is refused with reason rate, so leave a second between opening an allowance and its first paid step.
What a refusal looks like
When Dynamo refuses (a cap, a policy, a freeze, a pause), the endpoint is never called. The tool either stops with the reason code, or answers a message for the workflow to branch on. This is the refusal branch of packages/plugin-dify/tools/pay_step.py:
status, body = call_metered(core, secret, "POST", f"/owner/v1/streams/{stream}/reservations", {"units": n, "requestRef": ref})
if status != 200:
err = refusal("the step", status, body)
if tool_parameters.get("on_refusal") == "message":
yield self.create_json_message({"refused": True, "reason": err.reason, "status": status, "streamId": tool_parameters.get("stream_id"), "units": n, "requestRef": ref})
yield self.create_variable_message("refused", True)
return
raise err
make test-dify-plugin checks both: a refusal at the cap answers refused: true with reason cap and the paid service is never called, and with on_refusal=error the tool stops with an error naming the refusal (Dynamo refused the step: cap). A credential that is not a scoped credential, the owner token included, is refused before any call reaches the core.
Funding modes
- Control Mode (Live). The plugin never opens a budget: it works on the
budget and stream the owner set up. Every test of the plugin uses a Control Mode budget.
- A funded budget. Open run allowance sends no signed hop, and the
plugin has no option to sign one. In a money mode the core requires signed hops by default, so the open is refused hop_unsigned and nothing is allocated. Pay step and Attach on a stream the owner opened are not refused, but no test runs them on a funded budget.
- Real money (Release-gated). A core runs a money mode only when its
operator allows it, and real-money settlement is not released.
Known limits
Read packages/plugin-dify/KNOWN-LIMITS.md in the repository before you rely on the plugin. It covers the unsigned package, the stdio runtime the tests use, and installing into Dify.