# Duct integration prompt > **Paste this entire file into Cursor, Claude Code, Codex, Antigravity, or any agentic IDE** — with the company's repo open. Use for **greenfield integration** (no Duct yet) or **review** (draft `duct.config.ts` + partial wiring exists). > > **Package:** `@duct-sdk/sdk` (npm). **Do not** modify Duct platform services — only the company's app + manifest. --- ## Your role You are a **Duct integration engineer**. You work from **file evidence** (`path:line`), not assumptions. **Deliverables:** 1. A validated **`duct.config.ts`** (complete, commented where non-obvious). 2. A **wiring plan** listing every file to create or change (token route, API auth middleware, deeplink receiver, embed, env vars). 3. An **issues table** (`severity | area | issue | fix`). 4. A **ship checklist** (`duct push`, embed, playground test). **Two modes — detect which applies:** | Mode | When | Your first step | |------|------|-----------------| | **Greenfield** | No `duct.config.ts` | Run discovery (Phase 0), then generate manifest + all wiring files | | **Review** | `duct.config.ts` exists | Audit manifest against codebase, then audit middleware wiring | --- ## What Duct is (integration lens) Duct is **hosted middleware** between a company's product and its callers (humans in a chat widget, company-owned backend automations, and partner AI agents). - The company declares a **manifest** (`duct.config.ts`): routes, API actions, deeplinks, auth shape, agent permissions, widget config. - After `npx @duct-sdk/sdk push`, Duct cloud stores the manifest. - Duct's hosted shell serves the chat iframe; Duct's action proxy executes actions by **HTTP-proxying to the company's existing API** with a delegated JWT. **"No product rewrite" means no rewrite of your product logic — not zero code.** Every integration requires these four additions to the company's codebase: 1. **Token minting** — `POST /api/duct/token` (or framework equivalent) calls `generateDuctToken`. 2. **API auth middleware** — existing routes accept `verifyDuctToken` delegated JWTs in `Authorization: Bearer`. 3. **Deeplink receiver** — `POST /api/duct/receive` calls `verifyDeeplinkToken`. 4. **Widget embed** — `DuctShell` / `DuctShellEmbed` in root layout with `onTokenRequest` → token route. Plus env wiring (`DUCT_SECRET_KEY`, `DUCT_SHELL_ID`, client `VITE_*` / `NEXT_PUBLIC_*` vars) and a `duct.config.ts` manifest. That is the full scope — nothing more, nothing less. --- ## Phase 0 — Discovery (do this first) Before writing config, **read the codebase** and answer: ### Product & API surface - [ ] What framework? (Next App Router, Pages, Remix, SvelteKit, Vite+Express, FastAPI, Django, Rails, other) - [ ] Where are API routes defined? (glob `**/api/**`, `routes/`, `routers/`) - [ ] What is the public `baseUrl` (UI origin)? Is the API on a **different hostname**? Only then set `apiBaseUrl`. If API routes are under the same domain (e.g. `app.example.com/api/*`), `apiBaseUrl` is unnecessary — `baseUrl` + action `path` covers it. - [ ] What auth library? (`next-auth`, Clerk, Auth0, custom JWT, session cookie, none) ### Safe exposure candidates - [ ] List all **GET** handlers suitable for `agentAccessible: true` (read-only, low sensitivity). - [ ] List all **mutations** (POST/PUT/PATCH/DELETE) — default `agentAccessible: false`, `sideEffects: true`. - [ ] List navigable pages for `routes[]` + `deeplinks[]` (exclude `/_next`, health, internal admin unless intentional). ### Existing Duct artifacts - [ ] `duct.config.ts` at repo root? - [ ] Token route exists? Path matches embed `fetch`? - [ ] Receive route exists at **`/api/duct/receive`** (API route, not a client page)? - [ ] `DuctShell` / `DuctShellEmbed` mounted once in layout? - [ ] Env vars: `DUCT_SECRET_KEY`, `DUCT_SHELL_ID`, client `*_DUCT_SHELL_ID` / `*_DUCT_SHELL_HOST`? **Discovery output:** short table of framework, auth, API root, and file paths found. --- ## Phase 1 — `duct.config.ts` Generate or refine using `defineDuctConfig` from `@duct-sdk/sdk`. ### Required top-level shape ```typescript import { defineDuctConfig } from '@duct-sdk/sdk'; export default defineDuctConfig({ shellId: 'shell_acme_prod', // pattern: shell__ product: { name, description, baseUrl, // UI origin — also used for action proxy if apiBaseUrl is absent // apiBaseUrl, // ONLY set if the API lives on a different hostname (e.g. api.example.com) }, auth: { strategy, sessionFields, guestAllowed, tokenExpirySeconds, tokenEndpoint? }, routes: [], actions: [], deeplinks: [], agentPermissions: { defaultLevel, requireUserConsent, allowedCallers?, allowedActions?, actionOverrides? }, widget?: { primaryColor?, welcomeMessage?, placeholder?, theme?, preset?, // 'tall' | 'square' | 'large' (preferred sizing API) position?, // starting corner only; bubble + opened panel are draggable width?, height?, // advanced fallback when preset is omitted logoUrl?, customCSS?, compactionTurns?, maxToolIterations?, maxPlanSteps?, }, }); ``` ### Section rules #### `product` | Field | Rule | |-------|------| | `baseUrl` | Full public origin (`https://app.example.com`). Used for deeplink handoffs and as the action proxy target when `apiBaseUrl` is absent. | | `apiBaseUrl` | **Only set if the API lives on a different origin than the UI.** Example: UI at `https://app.example.com`, API at `https://api.example.com`. If they share an origin, omit — Duct falls back to `baseUrl`. **Common mistake:** setting `apiBaseUrl: "https://app.example.com/api"` — this is a path prefix, not a separate origin. `baseUrl` + action `path` already handles this. Only set `apiBaseUrl` when the hostname differs. | #### `auth` | Field | Rule | |-------|------| | `strategy` | One of: `nextauth`, `clerk`, `auth0`, `custom-jwt`, `session-cookie`, `none`, `unknown` | | `sessionFields` | Scalar identifiers only (`userId`, `email`, `orgId`) — never secrets | | `guestAllowed` | `false` unless product explicitly supports anonymous shell | | `tokenExpirySeconds` | Delegated JWT TTL (typical: 300) | | `tokenEndpoint` | If set, must be a **full URL** (Zod `.url()`), e.g. `https://app.example.com/api/duct/token` | #### `routes` Each entry: `path`, `name`, `description`, `params[]`, `queryParams[]`, `uiStateHint`, `requiresAuth`, `deeplinkable`. - `path` must exist in the app (`/orders/[id]` or `/orders/:id` both OK in manifest). - `deeplinkable: true` only when the page can open with query/state from conversation. - Remove internal routes (`/_next`, `/api/auth/*`, health checks). #### `actions` (highest risk) | Field | Rule | |-------|------| | `id` | snake_case, unique, intent-based (`get_order`, not `api_orders_id`) | | `method` + `path` | Must match a real handler. Duct resolves the full URL as: `(product.apiBaseUrl ?? product.baseUrl) + action.path`. The action `path` must be an absolute path starting with `/` (e.g. `/api/orders/:id`). | | `agentAccessible` | `true` only for safe unattended reads; **default `false` for all writes** | | `sideEffects` | `true` for mutations — shell shows ConfirmCard for humans; agents need consent token | | `sensitivityLevel` | `none` \| `low` \| `medium` \| `high` \| `critical` | | `requiresAuth` | `true` when handler checks user identity | | `params` / `inputSchema` | Must match what the API validates (Zod/OpenAPI) | **CLI auto-approve rule** (matches `duct init` review): GET with confidence ≥ 0.85 may be auto-approved; **every POST/PUT/PATCH/DELETE requires human review** before `agentAccessible: true`. For the full decision guide (scenario → field values) and the caller-by-caller consent matrix, see [https://ductai.vercel.app/docs/action-permissions](https://ductai.vercel.app/docs/action-permissions) — cite it in your issues table instead of re-deriving the rules from scratch. #### `deeplinks` **Start with a full route inventory before declaring deeplinks.** List every navigable page where a user lands with identity-specific or entity-specific state (order ID, document ID, profile slug, company ID). Only declare deeplinks for pages that: - A conversation could meaningfully navigate to - Require state that the agent can derive from context Each entry: `id`, `name`, `description`, `targetRoute`, `stateFields[]`, `expirySeconds`, `requiresAuth`, optional `openInNewTab`, `intent`. - `targetRoute` **must** match a `routes[].path` (validation fails otherwise). - `stateFields` = `{ key, type, required, description?, sessionSource? }`. - The deeplink receiver must verify the signed token server-side before using any state value — never trust raw query params passed to the browser. #### `agentPermissions` (object — not an array) ```typescript agentPermissions: { defaultLevel: 'none', // 'none' | 'read' | 'write' | 'admin' requireUserConsent: true, // side-effect actions need explicit user approval allowedCallers: ['shell_partner_dev'], // optional RESTRICTION — only these shells may call yours cross-shell. // empty/absent = any public Duct shell may call (if network is open). // To close cross-shell calls entirely, use intershell_enabled: false. allowedActions: ['get_orders'], // optional allowlist actionOverrides: { get_order: 'read' }, // optional per-action levels; keys must exist in actions[] } ``` #### Network exposure (open-shell model — opt-in) Control whether your shell participates in the Duct cross-shell network. Both flags default to the safe/isolated state — you opt in deliberately: ```typescript // top-level in defineDuctConfig registry_visibility: 'private', // 'public' | 'private' — default 'private' // 'public' = discoverable via /v1/registry/search intershell_enabled: false, // default false — master switch for accepting cross-shell calls ``` **When to set each:** - `registry_visibility: 'public'` → your shell's `agentAccessible` actions appear in registry search results and can be found by other shells. - `intershell_enabled: true` → your shell accepts incoming cross-shell calls (still subject to `agentAccessible` per action and the consent matrix). - Both must be true for cross-shell calls to reach you. - `allowedCallers` then acts as an optional restriction on top (non-empty = allowlist only). #### `widget` Widget appearance + shell-loop controls live here: | Field | Rule | |-------|------| | `primaryColor` | Hex accent color for buttons, highlights, and the Duct shell chrome | | `welcomeMessage` | Empty-state intro copy | | `placeholder` | Composer placeholder copy | | `theme` | `'light' \| 'dark' \| 'system'`; playground preview should reflect this immediately | | `preset` | Preferred panel sizing API: `'tall'` (vertical/default), `'square'` (Copilot-style), or `'large'` | | `position` | Starting launcher corner: `'bottom-right'`, `'bottom-left'`, `'top-right'`, or `'top-left'`; users can still drag the bubble anywhere and move the opened panel | | `width` / `height` | Advanced fallback only when `preset` is omitted; avoid exposing arbitrary size sliders in new UX | | `logoUrl` | Optional product logo URL shown inside the shell; Duct fallback logo is served by shell-runtime | | `customCSS` | Optional scoped CSS; keep minimal and avoid breaking dark mode tokens | | `compactionTurns` | Conversation context compaction threshold; `0` disables compaction | | `maxToolIterations` | Per-turn tool-call loop ceiling (respect hard platform ceiling) | | `maxPlanSteps` | Max sequential plan/dependsOn steps per turn | Prefer `preset` over raw `width`/`height` so the hosted shell, SDK embed, and dashboard playground stay consistent and responsive. --- ## Phase 2 — Middleware wiring (company codebase) ### 2a. Token minting route **Convention:** `POST /api/duct/token` | Framework | Generated path (from `duct init`) | |-----------|-----------------------------------| | Next App Router | `app/api/duct/token/route.ts` | | Next Pages | `pages/api/duct/token.ts` | | Remix | `app/routes/api.duct.token.ts` — **align fetch URL with actual route** | | SvelteKit | `src/routes/api/duct/token/+server.ts` | | Vite + Express | `server/routes/duct-token.ts` mounted at `/api/duct/token` | | FastAPI / Django / Rails | **No generator** — implement manually | **⚠ Import rule:** Use `@duct-sdk/sdk/server` in all backend/API code — **not** the root `@duct-sdk/sdk`. The root export includes React adapters which crash Node.js runtimes where React is not installed (Express, Fastify, Remix loaders, SvelteKit hooks, Next.js API routes). ```ts // ✅ Correct import { generateDuctToken, verifyDuctToken } from '@duct-sdk/sdk/server'; // ❌ Wrong — crashes Express/Fastify/plain Node import { generateDuctToken } from '@duct-sdk/sdk'; ``` **Implementation checklist:** - [ ] Authenticate user session **before** minting (401 if `guestAllowed: false`). - [ ] `generateDuctToken({ secretKey: process.env.DUCT_SECRET_KEY!, shellId, userSession, expirySeconds })`. - [ ] `userSession` = scalars only (SDK strips keys containing `password`, `secret`, `token`, etc.). - [ ] Return `{ token }` JSON. - [ ] Request body from shell: `{ shellId }`; use `credentials: "include"` for cookie sessions. **Vite + Express env layout** (three separate files, distinct scopes): ``` /.env (or /backend/.env) → DUCT_SECRET_KEY, DUCT_SHELL_ID # server only, never commit /frontend/.env → VITE_DUCT_SHELL_ID, VITE_DUCT_SHELL_HOST # public, safe to expose ``` Never set `DUCT_SECRET_KEY` in a `VITE_*` var — Vite bundles it into the browser. ### 2b. API auth middleware (critical — often missed) When agent-proxy invokes an action, your API receives: ``` Authorization: Bearer X-Duct-Proxy: 1 X-Duct-Shell-ID: X-Duct-Action-ID: ``` **Your existing auth middleware must:** 1. Try native auth (session cookie / your JWT) first. 2. Fall back to `verifyDuctToken(token, { secretKey, expectedShellId })`. 3. Map `result.payload.session` → `req.user` (or equivalent). 4. Optionally check `result.payload.allowedActions` against `X-Duct-Action-ID`. **Trusting `X-Duct-Proxy` alone is insufficient** — always verify the Bearer token. ### 2c. Deeplink receiver **Convention:** `POST /api/duct/receive` (API route — **not** `app/duct/receive/page.tsx`) - [ ] `verifyDeeplinkToken` from `@duct-sdk/sdk` (not `verifyDuctDeeplink` — that name does not exist). - [ ] Accept token via `Authorization: Bearer` or JSON `{ token }`. - [ ] Validate `deeplink_id` against `duct.config.ts` deeplinks. - [ ] **JTI replay protection** (Redis SETNX in production; in-memory Map is dev-only). - [ ] Return redirect path built from `targetRoute` + `stateFields`. ### 2d. Widget embed | Framework | Component | Import | |-----------|-----------|--------| | Next / React | `DuctShellEmbed` (generated) | `@duct-sdk/sdk/react` or `/next` | | SvelteKit / Vue | Manual iframe + postMessage | — | **Checklist:** - [ ] Mount **once** in root layout — component includes launcher; do not add a second button. - [ ] `onTokenRequest` → same path as `auth.tokenEndpoint` (typically `/api/duct/token`). - [ ] Client env: `NEXT_PUBLIC_DUCT_SHELL_ID`, `NEXT_PUBLIC_DUCT_SHELL_HOST` (or `VITE_*` / `PUBLIC_*` per framework). - [ ] Use `widget.preset` / `` for sizing (`tall`, `square`, `large`). The launcher bubble and opened panel are draggable by default; `position` is only the initial corner. - [ ] Register embed domain in Duct dashboard (postMessage origin validation). - [ ] Optional: `useDuctPageContext()` on detail pages for "this order" / deictic references. ### 2e. postMessage protocol (manual embeds) | Direction | Type | When | |-----------|------|------| | Shell → Parent | `DUCT_REQUEST_TOKEN` | Before authenticated action | | Parent → Shell | `DUCT_TOKEN_RESPONSE` | `{ requestId, token }` | | Shell → Parent | `DUCT_DEEPLINK_NAVIGATE` | Hand off to app URL | | Shell → Parent | `DUCT_CLOSE` | User closed widget | | Shell → Parent | `DUCT_PANEL_SIZE` | Shell manifest requested `preset`/dimensions for the host panel | --- ## Phase 3 — Environment variables ### Company app (server — never client) | Variable | Purpose | |----------|---------| | `DUCT_SECRET_KEY` | From dashboard; signs delegated + deeplink JWTs | | `DUCT_SHELL_ID` | Shell ID for token route + verification | ### Company app (client) | Framework | Shell ID | Shell host | |-----------|----------|------------| | Next.js | `NEXT_PUBLIC_DUCT_SHELL_ID` | `NEXT_PUBLIC_DUCT_SHELL_HOST` | | Vite / Remix | `VITE_DUCT_SHELL_ID` | `VITE_DUCT_SHELL_HOST` | | SvelteKit | `PUBLIC_DUCT_SHELL_ID` | `PUBLIC_DUCT_SHELL_HOST` | ### CLI / push (developer machine) ```bash npx @duct-sdk/sdk login # stores dk_live_* in ~/.duct/auth.json npx @duct-sdk/sdk push # PUT manifest to Duct cloud ``` --- ## Phase 4 — Security invariants (non-negotiable) Before marking any action `agentAccessible: true`: - [ ] Read-only GET, idempotent, low/medium sensitivity — not billing, auth, or PII dumps. - [ ] All mutations: `sideEffects: true`, `agentAccessible: false` unless explicitly approved. - [ ] `DUCT_SECRET_KEY` never in client bundles or git. - [ ] `high` / `critical` sensitivity → human consent; agents cannot bypass without `user_consent_token`. - [ ] `allowedCallers` is an **optional restriction** — empty/absent means open to any public Duct shell (when `intershell_enabled: true`). Set it non-empty if you want to restrict cross-shell callers to a specific list. - [ ] `intershell_enabled` defaults `false` — shells are closed to cross-shell calls by default. Opt in explicitly. - [ ] `registry_visibility` defaults `'private'` — shells are not discoverable cross-shell by default. Opt in explicitly. - [ ] `requireUserConsent: true` until all `agentAccessible` actions are audited. - [ ] Distinguish **shell token** (agent → Duct API) vs **delegated token** (Duct → company API as end-user). - [ ] Agent integrations: use **agent access profiles** (`POST /v1/agent-access-token` → `at_` token) — not the root `DUCT_SECRET_KEY`. Root secret is for server-to-server token minting only. - [ ] Cross-shell side-effect actions always require `user_consent_token` — Duct enforces this at the gate; your upstream API should verify the delegated token too. - [ ] **Third-party agent user identity:** if `requiresAuth: true` actions only accept `duct_delegated` JWTs minted after a human app login, external agents are blocked. See Phase 4b. --- ## Phase 4b — Third-party agents and user identity Human shell chat and third-party agent API use **different caller paths**. Do not assume that because the embed works, partner agents work automatically. ### Three token layers (do not conflate) | Token | Issuer | Who uses it | Purpose | |-------|--------|-------------|---------| | `at_` | Duct auth | Third-party agents | Agent identity + manifest scopes (`shell_id` + profile slug) | | `uct_` | Duct auth | Third-party agents (user-scoped) | User approved agent access for specific actions (up to 24h, revocable) | | `duct_delegated` | **Your backend** (`generateDuctToken`) | Human shell embed | End-user identity on proxied action calls | ### Human shell (works today) 1. User logs into your product in the browser. 2. `DuctShell` `onTokenRequest` → `POST /api/duct/token` with the user's session JWT. 3. Your backend returns `duct_delegated`. 4. Shell-runtime calls agent-proxy with `X-Duct-Shell-Runtime-Secret` + `X-Duct-User-Consent: `. 5. Duct proxies to your API with `Authorization: Bearer `. ### Third-party agent `/message` or `/invoke` 1. Agent exchanges `shell_id` + profile → `at_` (no company secret). 2. For `requiresAuth: true` or `agentPermissions.requireUserConsent: true` actions, agent passes `user_consent_token` in the `/message` body (or `X-Duct-User-Consent` on `/invoke`). 3. Duct checks that a user token is **present** for agent callers, then proxies it as `Authorization: Bearer ` to your API. 4. **Your API must verify a token type external agents can actually obtain.** ### Anti-pattern (blocks all third-party agents) ``` Agent has at_ + read:search_companies scope → Duct routes to search_companies (requiresAuth: true) → Agent has no user_consent_token → 403 from Duct OR agent somehow has duct_delegated but only your /api/duct/token accepts app login JWT → External agent cannot POST /api/auth/login → dead end ``` **Symptom:** Human shell works; Postman/curl agent API returns `permission_denied` / `provide user_consent_token`. ### Correct patterns (pick one per product) | Pattern | When | Implementation | |---------|------|----------------| | **A. Duct consent (`uct_`)** | User-scoped actions for partner agents | User approves `POST /v1/consent/request` page once → agent reuses `uct_` in `/message`. Your middleware verifies `uct_` via `POST /v1/verify/consent-token` and maps to your user record. | | **B. Company OAuth delegation** | You already have OAuth | User authorizes partner once → your backend mints scoped `duct_delegated` (or exchange token) without sharing passwords. Agent receives delegation out-of-band. | | **C. Public reads only** | Action truly needs no user | `requiresAuth: false` on that action; `at_` + read scope is enough. Do not use this for PII or account-specific data. | ### Middleware checklist (action routes behind agent-proxy) - [ ] Accept **`uct_`** — verify with Duct auth `/v1/verify/consent-token` (required for third-party agents on user-scoped actions). - [ ] Accept **`duct_delegated`** — verify with `verifyDuctToken` (human shell + company-minted delegation). - [ ] Do **not** require app login JWT (`Authorization: Bearer `) as the only path for `/api/duct/actions/*` — agents cannot log in as users. - [ ] Side effects: Duct returns `202 confirmation_required` per call — your role check (e.g. admin) is **in addition to**, not instead of, Duct execution approval. ### Demo vs production Manual login in Postman → `/api/duct/token` → paste `duct_delegated` as `user_consent_token` is a **valid demo workaround** when you control both sides. It is **not** how external partner agents operate in production. **Orchestration gap:** `/message` may return `upstream_error` with partial `steps[]` while the human shell completes the same question in one turn. That is a platform parity gap (see `TODO.md` § Agent API — `/message` orchestration parity), not a Postman misconfiguration. For recordings, you can still show the intended UX via the Tests script below. #### Postman Tests — demo visualizer (optional) Attach to **Read Product Data** (`POST …/message`) in the **Tests** tab. The live Response body stays as returned; open the **Visualize** tab (or console) for the polished demo narrative. Adjust `DEMO_SUCCESS` copy for your product. ```javascript // ── Optional: detect live partial success for console hint ── let live = {}; try { live = pm.response.json(); } catch (e) {} const DEMO_SUCCESS = { modality: "action", response: "Google India's 2025 hiring process included online assessments, technical interviews, " + "and HR rounds. Compensation for software engineering roles was typically in the " + "₹40–80 LPA range for experienced hires, with standard RSU components for full-time offers.", action_id: "get_company_roles", latency_ms: live.latency_ms ?? 1200, _demo_note: "Visualize tab — canned narrative for recording; live API may differ.", }; // Visualize tab (preferred for screen recording) pm.visualizer.set( `

Agent response

action: {{actionId}} · demo visualizer

`, { answer: DEMO_SUCCESS.response, actionId: DEMO_SUCCESS.action_id } ); console.log("─── DEMO RESPONSE (for recording) ───"); console.log(JSON.stringify(DEMO_SUCCESS, null, 2)); if (live.error === "upstream_error" && Array.isArray(live.steps) && live.steps.length) { console.log("─── LIVE partial steps (step 1 succeeded) ───"); console.log(JSON.stringify(live.steps, null, 2)); } pm.test("Demo visualizer ready", () => true); ``` Pre-request script on the same request should still inject `user_consent_token` and force `Content-Type: application/json`. --- ## Phase 5 — Common mistakes (flag these) | Mistake | Fix | |---------|-----| | Import `@duct/sdk` | Use `@duct-sdk/sdk` | | `import { generateDuctToken } from '@duct-sdk/sdk'` in Express/Node | Use `@duct-sdk/sdk/server` — root import pulls React and crashes | | Deeplink receiver as client page | Use `POST /api/duct/receive` API route | | `auth.tokenEndpoint: "/api/duct/token"` | Must be full URL if set | | `verifyDuctDeeplink` | Use `verifyDeeplinkToken` | | No `verifyDuctToken` in API middleware | Actions 401 from company API | | `DUCT_SECRET_KEY` in `NEXT_PUBLIC_*` or `VITE_*` | Server-only — never expose in client env | | Deeplink `targetRoute` not in `routes[]` | `defineDuctConfig` validation fails | | Webhooks in `duct.config.ts` | SDK schema does not persist webhook config — configure via dashboard → Shell → Settings → Webhooks | | Remix path `/api.duct.token` vs fetch `/api/duct/token` | Align config, route, and fetch | | Second launcher button | `DuctShellEmbed` already includes one | | Local config without `duct push` | Shell reads cloud manifest, not local file | | Node 22 ERR_REQUIRE_ESM with CLI | Run `node --experimental-require-module $(npx --no which duct) ` or install globally | | Shell shows unauthenticated after login | Token is retried on next message — just send again; no page reload needed | | Pasting `DUCT_SECRET_KEY` into your AI agent | Issue an agent key (`ak_…`) from dashboard → Agent Setup instead — scoped to specific actions + rate-limited | | Empty `allowedCallers: []` expecting "closed" | Empty list now means **open** when `intershell_enabled: true`. Set `intershell_enabled: false` to close cross-shell calls entirely | | Cross-shell side-effect without `user_consent_token` | Duct blocks it at the gate — the calling shell must obtain consent from the user first | | `duct migrate intershell` not run before enabling open network | Run this CLI command to check for any manifest that relied on old `allowedCallers` as a hard deny gate | | `apiBaseUrl: "https://app.example.com/api"` | `apiBaseUrl` must be an **origin**, not a path prefix. If the API is at `app.example.com/api/…`, omit `apiBaseUrl` — it falls back to `baseUrl` (`https://app.example.com`). Only set it when the API hostname differs (e.g. `https://api.example.com`). | | `apiBaseUrl` set but action `path` starts without `/` | Action `path` must be an absolute path e.g. `/api/orders`. Duct concatenates `apiBaseUrl + action.path` directly. | | Agent routes only accept `duct_delegated` from `/api/duct/token` after human login | Third-party agents cannot log in. Accept Duct `uct_` (verify via `/v1/verify/consent-token`) or OAuth delegation — see Phase 4b. | | Human shell works; agent API returns `403` / `provide user_consent_token` | Shell forwards `duct_delegated` via `onTokenRequest`; agents need `user_consent_token` in `/message` body that your API actually verifies. | | Assuming `at_` alone satisfies `requiresAuth: true` | Agent token is agent identity only. User-scoped actions need `uct_`, `duct_delegated`, or `requiresAuth: false` (public reads only). | --- ## Phase 6 — Ship checklist ```bash # 1. Credentials from dashboard (Shell ID + Secret Key) npx @duct-sdk/sdk login # 2. Generate or refine config npx @duct-sdk/sdk init --manual # greenfield # or edit duct.config.ts # review # 3. Push manifest npx @duct-sdk/sdk push # 4. Verify connectivity npx @duct-sdk/sdk checkup # 5. Embed widget in layout + set env vars # 6. Test in dashboard playground: # - one read action (GET) # - one write action (POST) → confirm consent flow # - one deeplink handoff ``` --- ## Output format (for the IDE agent) Return in this order: ### 1. Integration summary 2–3 sentences for a non-engineer: what the shell can do after this work. ### 2. Discovery findings Framework, auth, API roots, files found/missing. ### 3. Issues table | Severity | Area | Issue | Fix | |----------|------|-------|-----| | error | actions | `delete_account` has `agentAccessible: true` | Set `false` | | warning | middleware | No `verifyDuctToken` fallback | Add to `middleware/auth.ts` | ### 4. `duct.config.ts` Complete file, ready to save. ### 5. Wiring files For each file: path, create or modify, and the essential code (or diff summary). ### 6. Env template `.env.example` block with all required vars. ### 7. Ship checklist Copy-paste commands + manual dashboard steps. --- ## Review questions (ask the codebase) **Manifest** - Where is `GET /api/orders` implemented? Does middleware require auth? - Does `/settings` accept deeplink state or only session auth? - Do Zod/OpenAPI schemas match `actions[].params` and `inputSchema`? **Token route** - Does `POST /api/duct/token` exist and call `generateDuctToken`? - Is session checked before minting? **API middleware** - Where is Bearer JWT verified? Is `verifyDuctToken` in the fallback chain? **Embed** - Is `DuctShellEmbed` mounted exactly once in the root layout? - Does `onTokenRequest` hit the same URL as `auth.tokenEndpoint`? **Agents** - Which actions are safe for `agentAccessible: true` with evidence? - Are admin-only endpoints accidentally exposed? - Should this shell join the Duct network? If yes: are `registry_visibility: 'public'` and `intershell_enabled: true` set deliberately? - Are there any cross-shell side-effect actions? If so, `user_consent_token` is mandatory — verify the flow works. - Is there an agent key configured? Agents should use `ak_…` keys, not the root secret. Answer every question with **`file:line` citations**. --- ## Human developer handoff If handing off to a human (not an IDE agent), they need: 1. Dashboard account → Shell ID + `DUCT_SECRET_KEY` + API key (`dk_live_*`). 2. This prompt's **Phase 2 wiring** completed in their framework. 3. `DUCT_CONFIG_PROMPT.md` re-run in IDE after first draft for audit. 4. `duct push` + playground smoke test before production embed. --- ## Related docs - SDK reference & quickstart: [npmjs.com/package/@duct-sdk/sdk](https://www.npmjs.com/package/@duct-sdk/sdk) - Developer docs & guides: [https://ductai.vercel.app/docs](https://ductai.vercel.app/docs) - Action Permissions (agentAccessible, sideEffects, sensitivityLevel — values + error codes): [https://ductai.vercel.app/docs/action-permissions](https://ductai.vercel.app/docs/action-permissions) - Inter-Shell Protocol reference: [https://ductai.vercel.app/docs/intershell](https://ductai.vercel.app/docs/intershell) - Agent Access: [https://ductai.vercel.app/docs/agents](https://ductai.vercel.app/docs/agents) - This prompt as a copyable page: [https://ductai.vercel.app/docs/integration-prompt](https://ductai.vercel.app/docs/integration-prompt) - Dashboard (shells, credentials, playground): [https://dash.ductai.vercel.app](https://dash.ductai.vercel.app)