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:

allowance for this run under your delegated stream, and returns its stream_id.

headroom.

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

budget and stream the owner set up. Every test of the plugin uses a Control Mode budget.

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.

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.