# Dify Connector

The Dify connector maps configured Dify applications to native AIP
capabilities. It supports workflow, completion, chat, advanced chat, agent chat,
and agent API families without placing Dify DTOs in the AIP semantic core.

## Capability Mapping

Each configured app becomes `cap:dify:{app_id}`. Calls accept:

- `inputs` for Dify application variables;
- `query` or `prompt` for completion and chat families;
- a stable `user` value;
- `conversation_id`, `files`, and `auto_generate_name` where the Dify API
  family supports them.

Workflow applications call `/v1/workflows/run`, completion applications call
`/v1/completion-messages`, and chat families call `/v1/chat-messages`.

The capability contract advertises synchronous, asynchronous, streaming, and
cancellation support. Workflows and agent modes require AIP approval because
they may invoke downstream tools or produce customer-visible work. Automatic
retry, transactions, reconciliation, and rollback are not advertised.

## Streaming and Cancellation

Streaming invocation parses bounded Dify SSE frames, emits ordered native
`StreamChunk` records, retains the remote task id, and requires an explicit
terminal event. An upstream close without a terminal event is a failure.

Cancellation uses the app-family stop endpoint after the remote task id is
known. `DifyTaskStore` preserves the AIP action-to-task mapping. The in-memory
store is for tests; `FileDifyTaskStore` provides atomic single-host persistence.
Clustered deployments need an atomic shared implementation.

Human-input events map to native `requires_human` results. They do not bypass
AIP approval authority.

## Deployment Boundary

`aip-connector-dify` is an embeddable connector crate. The stock `aipd` 1.0
binary does not expose Dify app registration options. A deployment host must:

1. load app descriptors and API keys from deployment-owned configuration;
2. construct `DifyConnector` with at least one unique app id;
3. provide durable task correlation appropriate to its topology;
4. register the generated capabilities and frozen handlers with the gateway;
5. bind authenticated AIP tenants and policy before invocation.

Supported app mode strings are `workflow`, `completion`, `chat`,
`agent-chat`, `advanced-chat`, and `agent`. Unknown modes fail during connector
construction.

## Data and Identity

The current contract marks Dify payloads as confidential, PII-bearing, and
redaction-required. The connector uses one configured app API key and does not
implement frozen connector credential-handle routing. A multi-tenant deployment
must therefore isolate connector instances or add a deployment-owned
credential provider instead of accepting API keys in action input.

When `user` is omitted, the current mapper sends the fallback value `aip`.
Production hosts should supply a stable, non-secret, tenant-scoped external
user mapping so unrelated users do not share Dify conversation identity.

## Qualification Boundary

Deterministic tests cover app validation, request mapping, bounded SSE parsing,
stream chunks, cancellation correlation, human-input mapping, and file-store
restart behavior. A complete retained isolated-live campaign against a pinned
Dify deployment is absent.

Before production promotion, prove all configured app modes, provider errors,
cancellation races, stream disconnects, restart recovery, tenant isolation,
redaction, and downstream side effects against the exact artifact.

See [Conformance and Qualification](../reference/conformance.md),
[Implementation Status](../reference/implementation-status.md), and
[Pinned Upstream Baselines](upstream-baselines.md).