Skip to main content

​
Goal

DealDash exposes an authenticated AI Agent Connection section in /settings and an AI Agent Setup entry in /tools so operators can connect Claude Code, OpenAI/Codex, ChatGPT MCP clients, OpenClaw, or another tool-capable host without exposing backend secrets in the browser. This Settings surface is informational and diagnostic for setup, and operational for revoking user-approved persistent agent tokens. It does not mint service secrets, bypass approvals, or expose manager confirmation secrets. Non-technical users should start with Connect An AI Agent. This page remains the agent/developer reference for exact response fields and safety rules.

​
Settings Endpoint

The endpoint returns env names, boolean configuration flags, token last-four, and timestamps only. It never returns raw tokens, token hashes, or secret values.

​
Response Sections

  • schemaVersion: current DealDash Agent Bridge schema version.
  • actingUserId: current authenticated DealDash user ID, retained for internal diagnostics only.
  • status: login-link availability, approval confirmation configured, state, recent count, and last activity.
  • advancedAuth: persistent login-link mode, direct start URL, revoke endpoint, token TTL windows, supported hosts, dynamic tool-discovery source, and safety copy.
  • mcp: server name, single bridge runtime model, bridge path, config path, command, backend base URL, direct HTTPS fallback URLs, simple docs URL, agent-optimized docs URL, and private DealDash Agent Kit GitHub repo for install/examples.
  • auth: login-link endpoints, safe optional env names, required headers, and optional headers.
  • permissions: Tier 0, Tier 1, and Tier 2 summaries.
  • toolGroups: canonical provider-neutral tool families from the shared schema.
  • workflows: common link, screenshot, template, contact, and suggestion workflows.
  • futureFeatures: planned analysis, summaries, approval inbox, and adapter diagnostics.
  • persistentConnections: approved user-owned agent auth requests with display name, actor, channel, scopes, token last-four, approval time, token claim time, token expiry time, last matching activity timestamp, and revoke endpoint.
  • recentLogs: sanitized agent_tool_call activity scoped to the current user.

​
UI Map

The Tools hub includes:
  • /tools card: AI Agent Setup, simple setup badge, and docs link.
  • /tools/ai-agent-setup: human-first setup steps, copyable AI instruction, good first requests, confusion fixes, optional terminal examples, common blockers, and an advanced connection panel hidden behind Show details.
The connection card contains:
  • Header and refresh action.
  • Connection status, permission gate, and recent activity cards.
  • Advanced persistent connection panel with token window, supported hosts, dynamic tool-discovery explanation, connected-agent rows, and revoke buttons.
  • DealDash Agent Bridge instructions with repo-local .mcp.json, server command, and direct HTTPS fallback URLs.
  • Login-link auth endpoints, the direct HTTPS login start URL, token env name, and operator-only env/header diagnostics.
  • Tier 0/Tier 1/Tier 2 permission explanation.
  • Tool family summary.
  • Recent user-scoped agent logs.
  • Future AI feature slots for analysis and summaries.
  • Links to the simple human guide, private DealDash Agent Kit for install/examples, agent-optimized bridge reference, and API docs.

​
Hermes Operator Baseline

Hermes should be treated as the preferred long-running DealDash operator host when it is available. OpenClaw remains an optional WhatsApp/Telegram channel adapter layered on the provider-neutral DealDash Agent Bridge, not the primary DealDash identity.
  • Preferred transport: dealdash-agent-bridge MCP. Fallback: direct HTTPS /api/agent/* after login-link auth.
  • Direct HTTPS identity: use actorId="hermes-agent" and channel="hermes" when starting auth so Settings logs, revocation rows, and learning audits remain recognizable.
  • Token handling: store the approved DealDash token only in the Hermes secure profile or secret store. Do not write it into chat, profile prose, GBrain, screenshots, logs, or memory pages.
  • Session startup: refresh GET /api/settings/agent-connection and GET /api/agent/schema or MCP tools/list before relying on stale instructions.
  • Self-improvement: graduate only verified, source-labeled preferences or workflow corrections from DealDash tool output, GBrain pages with source labels, or explicit operator correction. Never learn from guesses, raw private messages, raw payment payloads, device codes, or tokens.
  • Write posture: start read-only, then report the account/data visible, planned tool, and approval tier before writes. Deletes always remain approval-gated.

​
Security Rules

  • Do not show or set DEALDASH_AGENT_SERVICE_SECRET from the browser.
  • Do not show or set DEALDASH_AGENT_APPROVAL_CONFIRM_SECRET from the browser.
  • Do not show raw login-link tokens or token hashes from the browser.
  • Normal users approve /agent/authorize/:requestId; they do not paste API keys, service secrets, or internal IDs.
  • Agents without MCP connected may still start normal setup with POST https://dealdash.tech/api/agent/auth/start, send only the returned approval link to the user, then call /api/agent/* directly with the stored login token.
  • Approved agent tokens are long-lived, renewable, and revocable from Settings. Defaults are 30 days with a server cap of 365 days.
  • Revocation must be scoped by both request ID and req.user.userId.
  • Public docs and the private agent kit must use placeholders only and must not include real tokens, database URLs, user data, or private local paths.
  • Scope logs by req.user.userId.
  • Sanitize logs to safe metadata only.
  • Clamp log limits to 1-50 rows.
  • Keep Tier 2 writes approval-gated for every host client; LinkShot bulk view-check imports are Tier 1 and should not request approval.
  • Persistent LinkShot view-log writes still require source URL, proof screenshot, platform, visible date, view count, and direct proof agreement.
  • Treat OpenClaw as an optional WhatsApp/Telegram adapter on top of the provider-neutral DealDash Agent Bridge.