Assisted Action Authoring

An AI-assisted, governed workbench for authoring connector functions — draft, compile, dry-run, repair, and stage a deployment proposal without bypassing certification or promotion gates.

Assisted Authoring is a just-in-time workbench for building a single connector function with an agent in the loop. Where Building a Provider documents the manual paths — declarative ProviderSpec manifests and hand-written Go — this is the assisted alternative: an agent proposes function source, Ductor compiles and dry-runs it through governed runtimes, and every iteration is recorded as auditable lineage. Nothing here bypasses the same certification, promotion, artifact-graph, and rollout-evidence gates that manual providers pass through; it only front-loads the write-and-verify loop.

All endpoints live under /api/connectors/authoring and are tenant- and environment-scoped.

Assisted Authoring produces a deployment proposal, not a live connector. The proposal still has to be promoted through your normal operations workspace and rollout gates before it serves traffic.

When to use it

Use assisted authoring when you need a single connector function and can describe the intended provider, integration, function name, function kind, and environment before the work starts. It is the no-code/operator path for the same connector lifecycle documented in Building a Provider: the agent helps draft source, while Ductor compiles, dry-runs, records repairs, evaluates readiness, and produces a staged proposal.

The outcome is deliberately narrow: a ready proposal attached to the operations workspace. It does not create a live connection, skip certification, activate an integration deployment, or bypass the marketplace and rollout evidence gates.

What you provide

The operator supplies the session scope (provider_key, integration_key, function_name, function_kind, and environment_id) and an intent that is specific enough for the agent to draft the function. Each source draft then records provenance and a hash-bound redacted source reference, so subsequent compile, dry-run, repair, and readiness records can be replayed as one lineage.

Review before proposal

Before creating a proposal, review the same surfaces readiness evaluates:

Setup readiness, permissions, entitlements, mutation semantics, field catalog, secret references, certification, promotion, artifact graph, and rollout evidence have no blockers.
Dry-runs used sandbox, fixture, or other non-production inputs unless allows_production_data was deliberately permitted.
Failed compile or dry-run attempts are linked to repairs with a reason, rather than replaced by disconnected drafts.
The action's write behavior matches the semantics expected by connector certification and deployment promotion.
Any connection or credential work stays in the connector connection lifecycle; the authoring session never exposes stored credentials.

The loop

A session walks a draft from intent to a staged proposal. The compile → dry-run → repair cycle repeats until readiness evaluates clean.

Endpoints

Prop

Type

Walking a session

Create a session and declare intent

A session pins the provider_key, integration_key, function_name, and function_kind you are authoring for, plus an environment_id. Intent is the agent-readable description of what the function should do; set it at creation or update it later with PUT .../intent.

curl -X POST http://localhost:8080/api/connectors/authoring/sessions \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "env-dev",
    "provider_key": "acme-crm",
    "function_name": "upsert_contact",
    "function_kind": "mutation"
  }'

Submit a source draft

Post the generated function source for the session. Ductor stores a hash-bound redacted source reference in the authoring record, not unrestricted raw source — the draft is content-addressed and its provenance (generated_by, provenance) is captured. Chain iterations with parent_draft_id and a reason.

Compile, then dry-run

attempts:compile runs the draft through the governed connector-function runtime. Once a draft compiles, attempts:dry-run executes it against sandbox, fixture, or other non-production inputs — allows_production_data defaults off and must be set deliberately. Fetch a specific attempt later with GET /compile-attempts/{id} or GET /dry-run-attempts/{id}.

Dry-run is for test inputs. Do not point it at production payloads unless your environment and entitlements explicitly permit it via allows_production_data.

Record repairs

When a compile or dry-run fails, POST .../repairs links the failed attempt to the next draft and a repair reason. This is what makes the fix history a first-class, replayable lineage rather than a series of disconnected edits.

Evaluate readiness

readiness:evaluate is the gate. It returns allowed plus a list of blockers, each with a surface, reason_code, and detail. Surfaces cover setup readiness, permissions, entitlements, mutation semantics, field catalog, secret references, certification, promotion, artifact graph, and rollout evidence. You cannot create a proposal while blockers remain.

Propose and attach to the workspace

POST .../proposals is accepted only after compile, dry-run, and readiness evidence are satisfied. POST /proposals/{id}:attach-to-workspace then stages the ready proposal into the governed operations workspace and returns a proposed change — the hand-off into your normal promotion and rollout flow.

Audit and replay

GET /sessions/{id}/timeline returns the full record — drafts, compile and dry-run attempts, repairs, proposals, and receipts — for one session. Because every step is content-addressed and linked, the timeline is a complete, replayable audit of how a function was authored and verified. :archive retires a session without mutating any connector runtime state.

How this relates to the rest of connectors

Generated configuration enters the existing connector lifecycle only after the ready proposal is attached to the operations workspace. From there, certification scorecards, deployment diffs, destructive-change previews, and promotion gates decide whether it can become active connector behavior.