Configuration

Minimal Manifest

import { defineDuctConfig } from '@duct-sdk/sdk';

Top-Level Sections

Widget appearance

Theme, size preset, welcome text, placeholder, and accent color can be set in duct.config.ts → widget or saved from Dashboard → Playground → Customize. Whichever you update most recently wins on the live shell. Agent-loop limits (maxToolIterations, maxPlanSteps, compactionTurns) still follow your manifest push when provided.

Product fields

Auth fields

The auth block controls how the embed requests delegated user tokens and where unauthenticated guests are sent when they ask for protected data.

Action security fields

Every action declares agentAccessible, sideEffects, sensitivityLevel, and requiresAuth. They are enforced before Duct calls your API — for human chat, Agent API, and cross-shell callers.

requiresAuth and programmatic callers

Whether the action needs an authenticated end-user on your API. For programmatic callers, Duct blocks the call unless user_consent_token is present. Company backends typically pass duct_delegated minted server-side; partner agents use uct_ or company OAuth delegation. Your API must accept token types each caller can actually obtain — not only session JWTs from your login form.

Action chaining (dependsOn)

Declare hard ordering between actions with dependsOn on the consumer action. Each entry names a prerequisite action and optional paramMapping from the dependency's response fields into params for the dependent step.

{

The human shell expands the DAG when the router picks a dependent action. POST /v1/shells/:id/message does the same — prerequisites run in order inside one orchestration turn. Use POST /invoke when your agent already has all params.

Manifest Versions & Side-Effect Changes

Every npx @duct-sdk/sdk push (and every rollback or promote) increments manifest_version. After activation, enforcement uses the current live manifest — cache invalidation runs on push, and versioned cache keys mitigate concurrent stale refills — so updated permissions apply promptly under normal conditions. Permission and consent checks always evaluate the current version, not the version in effect when a chat session started.

Human chat (ConfirmCard)

The next time the shell invokes that action, the user sees a ConfirmCard and must approve before anything reaches your API. Each side-effect call requires its own confirmation — there is no blanket “user already consented in this session” bypass for mutations.

While a confirmation card, in-chat form, or multiple-choice clarification is showing, the message input is disabled until the user responds on that card — so accidental typing cannot interrupt an approval or disambiguation step.

Agent API

Side-effect actions return 202 confirmation_required with a short-lived execution_token on every call, even when a valid X-Duct-User-Consent header is present. A user consent token authorizes the agent to request execution; it does not auto-execute irreversible work. If the action newly requires side-effect handling, agents without a consent token receive 403 until the user approves through your consent flow.

Confirmation approval mode

Set DUCT_APPROVAL_MODE on the platform stack. Default operator_session requires a signed-in dashboard operator to approve side-effect confirmations. Set link_holder to allow independent agents to forward approval_url to a human browser — this proves channel possession, not verified human identity (optional CAPTCHA via DUCT_APPROVAL_CAPTCHA_*). Legacy DUCT_STRICT_OPERATOR_APPROVAL=true maps to operator_session.

User consent after a manifest change

Consent is bound to what the user approved — not just the action name. If you change an action's method, path, sideEffects, or sensitivityLevel and push, existing user_consent_token values no longer cover that action. The next invoke returns 409 until the user re-approves through your consent flow. Tokens that still match the current definition remain valid until expiry (24 hours) or explicit revocation.

Side-effect confirmation is separate: even with a valid consent token, agents still receive 202 confirmation_required on each mutating call.

Agent tokens after a push

Agent access profiles exchange for short-lived tokens tied to the manifest version at exchange time. After push, rollback, or promote, invoke may return 409 with MANIFEST_STALE until the agent re-exchanges at /v1/agent-access-token. See agent access after a push.

Session notice

Chat sessions started before a push may show a soft “shell configuration updated” banner. Enforcement still uses the latest manifest; the banner is a UX hint that action schemas may have changed mid-conversation.

What Is Not In duct.config.ts

The manifest controls the shell's capabilities. A few settings live outside it and are managed elsewhere: