mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-08 22:22:17 +02:00
feat(agents): consolidate connectors under mcp_discovery; route web search through google_search
MCP consolidation: - Route all MCP-capable connectors (Slack, Jira, Linear, ClickUp, Airtable, Notion, Confluence, interim Gmail/Calendar, custom MCP) through a single `mcp_discovery` subagent. Drive/OneDrive/Dropbox stay native to enrich the KB. - Deprecate Discord/Teams/Luma: no viable official MCP server. Google-only web search: - Remove the main-agent `web_search` tool and the SearXNG platform service; all public web search now flows through the `google_search` subagent via task(). - Deprecate the Tavily/SearXNG/Linkup/Baidu search connectors (HTTP 410 on create, "Deprecated" badge); guide heavy users to the custom MCP connector. - Remove web search from anonymous chat (pure Q&A). - Tear SearXNG out of docker compose + install scripts; drop tavily-python and linkup-sdk deps and their config/env vars. Fix: - metrics._package_version() now swallows any metadata lookup failure. A malformed editable-install distribution with no `Version` field raised KeyError deep in importlib.metadata, and since it runs on every record_subagent_invoke_duration call it was crashing every task() delegation. Verified end-to-end against live GPT-5.4. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
DESKTOP-RTLN3BA\$punk
parent
ff2e5f390f
commit
ab747e7a49
206 changed files with 1704 additions and 7223 deletions
|
|
@ -333,16 +333,6 @@ STT_SERVICE=local/base
|
|||
# GATEWAY_DISCORD_ENABLED=FALSE
|
||||
# GATEWAY_DISCORD_REDIRECT_URI=http://localhost:3929/api/v1/gateway/discord/callback
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# SearXNG (bundled web search, works out of the box with no config needed)
|
||||
# ------------------------------------------------------------------------------
|
||||
# SearXNG provides web search to all search spaces automatically.
|
||||
# To access the SearXNG UI directly in dev/deps-only compose: http://localhost:8888
|
||||
# To disable the service entirely: docker compose up --scale searxng=0
|
||||
# To point at your own SearXNG instance instead of the bundled one:
|
||||
# SEARXNG_DEFAULT_HOST=http://your-searxng:8080
|
||||
# SEARXNG_SECRET=surfsense-searxng-secret
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Daytona Sandbox (optional cloud code execution for the deep agent)
|
||||
# ------------------------------------------------------------------------------
|
||||
|
|
@ -492,9 +482,6 @@ NOLOGIN_MODE_ENABLED=FALSE
|
|||
# -- Redis exposed port (dev/deps-only only; Redis is internal-only in prod) --
|
||||
# REDIS_PORT=6379
|
||||
|
||||
# -- SearXNG exposed port (dev/deps-only only; internal-only in prod) --
|
||||
# SEARXNG_PORT=8888
|
||||
|
||||
# -- WhatsApp bridge exposed port (dev/hybrid only; prod keeps it Docker-internal) --
|
||||
# WHATSAPP_BRIDGE_PORT=9929
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# =============================================================================
|
||||
# SurfSense — Dependencies only (no backend / frontend / Celery images)
|
||||
# =============================================================================
|
||||
# Postgres, Redis, SearXNG, pgAdmin, Zero — run API + Next + Celery on the host.
|
||||
# Postgres, Redis, pgAdmin, Zero — run API + Next + Celery on the host.
|
||||
# Celery is not Dockerized here: use `uv run` from surfsense_backend/ (no extra
|
||||
# backend image build just for workers).
|
||||
#
|
||||
|
|
@ -9,7 +9,7 @@
|
|||
# docker compose -f docker/docker-compose.deps-only.yml up -d
|
||||
#
|
||||
# Compose variable substitution uses `docker/.env` (copy from .env.example).
|
||||
# Bind mounts use ./postgresql.conf and ./searxng in this directory.
|
||||
# Bind mounts use ./postgresql.conf in this directory.
|
||||
#
|
||||
# Local Celery (from surfsense_backend/, after Redis is up):
|
||||
# uv run celery -A celery_worker.celery_app worker --loglevel=info --concurrency=1 --pool=solo --queues=surfsense,surfsense.connectors
|
||||
|
|
@ -17,7 +17,6 @@
|
|||
#
|
||||
# Host setup:
|
||||
# - Backend .env: DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/surfsense
|
||||
# - Backend .env: SEARXNG_DEFAULT_HOST=http://localhost:${SEARXNG_PORT:-8888}
|
||||
# - Backend .env: CELERY_BROKER_URL / REDIS_APP_URL → redis://localhost:6379/0
|
||||
# - Web .env: NEXT_PUBLIC_ZERO_CACHE_URL=http://localhost:${ZERO_CACHE_PORT:-4848}
|
||||
#
|
||||
|
|
@ -80,20 +79,6 @@ services:
|
|||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
searxng:
|
||||
image: searxng/searxng:2026.3.13-3c1f68c59
|
||||
ports:
|
||||
- "${SEARXNG_PORT:-8888}:8080"
|
||||
volumes:
|
||||
- ./searxng:/etc/searxng
|
||||
environment:
|
||||
- SEARXNG_SECRET=${SEARXNG_SECRET:-surfsense-searxng-secret}
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/healthz"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
# NOTE: zero-cache requires the `zero_publication` Postgres publication to
|
||||
# exist before it starts. In this deps-only stack there is no backend
|
||||
# container to run migrations, so you must run `uv run alembic upgrade head`
|
||||
|
|
|
|||
|
|
@ -85,20 +85,6 @@ services:
|
|||
- "${OTEL_TEMPO_PORT:-3200}:3200"
|
||||
restart: unless-stopped
|
||||
|
||||
searxng:
|
||||
image: searxng/searxng:2026.3.13-3c1f68c59
|
||||
ports:
|
||||
- "${SEARXNG_PORT:-8888}:8080"
|
||||
volumes:
|
||||
- ./searxng:/etc/searxng
|
||||
environment:
|
||||
- SEARXNG_SECRET=${SEARXNG_SECRET:-surfsense-searxng-secret}
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/healthz"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
backend:
|
||||
build: *backend-build
|
||||
ports:
|
||||
|
|
@ -125,7 +111,6 @@ services:
|
|||
- LANGSMITH_TRACING=false
|
||||
- AUTH_TYPE=${AUTH_TYPE:-LOCAL}
|
||||
- NEXT_FRONTEND_URL=${NEXT_FRONTEND_URL:-http://localhost:3000}
|
||||
- SEARXNG_DEFAULT_HOST=${SEARXNG_DEFAULT_HOST:-http://searxng:8080}
|
||||
- WHATSAPP_BRIDGE_URL=${WHATSAPP_BRIDGE_URL:-http://whatsapp-bridge:9929}
|
||||
# Daytona Sandbox – uncomment and set credentials to enable cloud code execution
|
||||
# - DAYTONA_SANDBOX_ENABLED=TRUE
|
||||
|
|
@ -138,8 +123,6 @@ services:
|
|||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
searxng:
|
||||
condition: service_healthy
|
||||
migrations:
|
||||
condition: service_completed_successfully
|
||||
healthcheck:
|
||||
|
|
@ -186,7 +169,6 @@ services:
|
|||
- CELERY_TASK_DEFAULT_QUEUE=surfsense
|
||||
- PYTHONPATH=/app
|
||||
- FILE_STORAGE_LOCAL_PATH=/app/.local_object_store
|
||||
- SEARXNG_DEFAULT_HOST=${SEARXNG_DEFAULT_HOST:-http://searxng:8080}
|
||||
- SERVICE_ROLE=worker
|
||||
depends_on:
|
||||
db:
|
||||
|
|
|
|||
|
|
@ -81,19 +81,6 @@ services:
|
|||
# timeout: 5s
|
||||
# retries: 3
|
||||
|
||||
searxng:
|
||||
image: searxng/searxng:2026.3.13-3c1f68c59
|
||||
volumes:
|
||||
- ./searxng:/etc/searxng
|
||||
environment:
|
||||
SEARXNG_SECRET: ${SEARXNG_SECRET:-surfsense-searxng-secret}
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/healthz"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
# Single public entry point for the Docker stack. Comment this service out
|
||||
# only if you front SurfSense with your own reverse proxy.
|
||||
proxy:
|
||||
|
|
@ -146,7 +133,6 @@ services:
|
|||
FILE_STORAGE_LOCAL_PATH: /app/.local_object_store
|
||||
NEXT_FRONTEND_URL: ${NEXT_FRONTEND_URL:-${SURFSENSE_PUBLIC_URL:-http://localhost:${LISTEN_HTTP_PORT:-3929}}}
|
||||
BACKEND_URL: ${BACKEND_URL:-${SURFSENSE_PUBLIC_URL:-http://localhost:${LISTEN_HTTP_PORT:-3929}}}
|
||||
SEARXNG_DEFAULT_HOST: ${SEARXNG_DEFAULT_HOST:-http://searxng:8080}
|
||||
WHATSAPP_BRIDGE_URL: ${WHATSAPP_BRIDGE_URL:-http://whatsapp-bridge:9929}
|
||||
# Daytona Sandbox – uncomment and set credentials to enable cloud code execution
|
||||
# DAYTONA_SANDBOX_ENABLED: "TRUE"
|
||||
|
|
@ -161,8 +147,6 @@ services:
|
|||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
searxng:
|
||||
condition: service_healthy
|
||||
migrations:
|
||||
condition: service_completed_successfully
|
||||
restart: unless-stopped
|
||||
|
|
@ -210,7 +194,6 @@ services:
|
|||
CELERY_TASK_DEFAULT_QUEUE: surfsense
|
||||
PYTHONPATH: /app
|
||||
FILE_STORAGE_LOCAL_PATH: /app/.local_object_store
|
||||
SEARXNG_DEFAULT_HOST: ${SEARXNG_DEFAULT_HOST:-http://searxng:8080}
|
||||
SERVICE_ROLE: worker
|
||||
depends_on:
|
||||
db:
|
||||
|
|
|
|||
|
|
@ -329,7 +329,6 @@ Write-Step "Downloading SurfSense files"
|
|||
Write-Info "Installation directory: $InstallDir"
|
||||
|
||||
New-Item -ItemType Directory -Path "$InstallDir\scripts" -Force | Out-Null
|
||||
New-Item -ItemType Directory -Path "$InstallDir\searxng" -Force | Out-Null
|
||||
New-Item -ItemType Directory -Path "$InstallDir\proxy" -Force | Out-Null
|
||||
|
||||
$Files = @(
|
||||
|
|
@ -339,8 +338,6 @@ $Files = @(
|
|||
@{ Src = "docker/proxy/Caddyfile"; Dest = "proxy/Caddyfile" }
|
||||
@{ Src = "docker/postgresql.conf"; Dest = "postgresql.conf" }
|
||||
@{ Src = "docker/scripts/migrate-database.ps1"; Dest = "scripts/migrate-database.ps1" }
|
||||
@{ Src = "docker/searxng/settings.yml"; Dest = "searxng/settings.yml" }
|
||||
@{ Src = "docker/searxng/limiter.toml"; Dest = "searxng/limiter.toml" }
|
||||
)
|
||||
|
||||
foreach ($f in $Files) {
|
||||
|
|
|
|||
|
|
@ -332,7 +332,6 @@ SELECTED_VARIANT=$(resolve_variant)
|
|||
step "Downloading SurfSense files"
|
||||
info "Installation directory: ${INSTALL_DIR}"
|
||||
mkdir -p "${INSTALL_DIR}/scripts"
|
||||
mkdir -p "${INSTALL_DIR}/searxng"
|
||||
mkdir -p "${INSTALL_DIR}/proxy"
|
||||
|
||||
FILES=(
|
||||
|
|
@ -342,8 +341,6 @@ FILES=(
|
|||
"docker/proxy/Caddyfile:proxy/Caddyfile"
|
||||
"docker/postgresql.conf:postgresql.conf"
|
||||
"docker/scripts/migrate-database.sh:scripts/migrate-database.sh"
|
||||
"docker/searxng/settings.yml:searxng/settings.yml"
|
||||
"docker/searxng/limiter.toml:searxng/limiter.toml"
|
||||
)
|
||||
|
||||
for entry in "${FILES[@]}"; do
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
[botdetection.ip_limit]
|
||||
link_token = false
|
||||
|
||||
[botdetection.ip_lists]
|
||||
pass_ip = ["0.0.0.0/0"]
|
||||
|
|
@ -1,90 +0,0 @@
|
|||
use_default_settings:
|
||||
engines:
|
||||
remove:
|
||||
- ahmia
|
||||
- torch
|
||||
- qwant
|
||||
- qwant news
|
||||
- qwant images
|
||||
- qwant videos
|
||||
- mojeek
|
||||
- mojeek images
|
||||
- mojeek news
|
||||
|
||||
server:
|
||||
secret_key: "override-me-via-env"
|
||||
limiter: false
|
||||
image_proxy: false
|
||||
method: "GET"
|
||||
default_http_headers:
|
||||
X-Robots-Tag: "noindex, nofollow"
|
||||
|
||||
search:
|
||||
formats:
|
||||
- html
|
||||
- json
|
||||
default_lang: "auto"
|
||||
autocomplete: ""
|
||||
safe_search: 0
|
||||
ban_time_on_fail: 5
|
||||
max_ban_time_on_fail: 120
|
||||
suspended_times:
|
||||
SearxEngineAccessDenied: 3600
|
||||
SearxEngineCaptcha: 3600
|
||||
SearxEngineTooManyRequests: 600
|
||||
cf_SearxEngineCaptcha: 7200
|
||||
cf_SearxEngineAccessDenied: 3600
|
||||
recaptcha_SearxEngineCaptcha: 7200
|
||||
|
||||
ui:
|
||||
static_use_hash: true
|
||||
|
||||
outgoing:
|
||||
request_timeout: 12.0
|
||||
max_request_timeout: 20.0
|
||||
pool_connections: 100
|
||||
pool_maxsize: 20
|
||||
enable_http2: true
|
||||
extra_proxy_timeout: 10
|
||||
retries: 1
|
||||
# Uncomment and set your residential proxy URL to route search engine requests through it.
|
||||
# Format: http://<username>:<base64_password>@<hostname>:<port>/
|
||||
#
|
||||
# proxies:
|
||||
# all://:
|
||||
# - http://user:pass@proxy-host:port/
|
||||
|
||||
engines:
|
||||
- name: google
|
||||
disabled: false
|
||||
weight: 1.2
|
||||
retry_on_http_error: [429, 503]
|
||||
- name: duckduckgo
|
||||
disabled: false
|
||||
weight: 1.1
|
||||
retry_on_http_error: [429, 503]
|
||||
- name: brave
|
||||
disabled: false
|
||||
weight: 1.0
|
||||
retry_on_http_error: [429, 503]
|
||||
- name: bing
|
||||
disabled: false
|
||||
weight: 0.9
|
||||
retry_on_http_error: [429, 503]
|
||||
- name: wikipedia
|
||||
disabled: false
|
||||
weight: 0.8
|
||||
- name: stackoverflow
|
||||
disabled: false
|
||||
weight: 0.7
|
||||
- name: yahoo
|
||||
disabled: false
|
||||
weight: 0.7
|
||||
retry_on_http_error: [429, 503]
|
||||
- name: wikidata
|
||||
disabled: false
|
||||
weight: 0.6
|
||||
- name: currency
|
||||
disabled: false
|
||||
- name: ddg definitions
|
||||
disabled: false
|
||||
|
|
@ -55,18 +55,6 @@ WHATSAPP_WEBHOOK_VERIFY_TOKEN=
|
|||
WHATSAPP_WEBHOOK_APP_SECRET=
|
||||
WHATSAPP_BRIDGE_URL=http://whatsapp-bridge:9929
|
||||
|
||||
# Platform Web Search (SearXNG)
|
||||
# Set this to enable built-in web search. Docker Compose sets it automatically.
|
||||
# Only uncomment if running the backend outside Docker (e.g. uvicorn on host).
|
||||
# SEARXNG_DEFAULT_HOST=http://localhost:8888
|
||||
|
||||
# web.discover fallback providers (env-keyed). SearXNG above is preferred; these
|
||||
# are used when it is not configured. web.discover self-disables if none are set.
|
||||
# LINKUP_API_KEY=
|
||||
# BAIDU_API_KEY=
|
||||
# BAIDU_MODEL=ernie-3.5-8k
|
||||
# BAIDU_SEARCH_SOURCE=baidu_search_v2
|
||||
|
||||
# Periodic task interval
|
||||
# # Run every minute (default)
|
||||
# SCHEDULE_CHECKER_INTERVAL=1m
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
"""Minimal anonymous / free-chat agent.
|
||||
|
||||
The no-login chat experience must stay dead simple: the user asks a question
|
||||
and the model answers, optionally using ``web_search`` and an optionally
|
||||
uploaded **read-only** document. We deliberately bypass the full SurfSense deep
|
||||
agent stack (filesystem, file-intent, knowledge-base persistence, subagents,
|
||||
skills, memory) because those middlewares stage or persist "documents" that an
|
||||
anonymous session can never see again -- which produced phantom
|
||||
"I saved it to a file" answers for free users.
|
||||
and the model answers over an optionally uploaded **read-only** document. We
|
||||
deliberately bypass the full SurfSense deep agent stack (filesystem,
|
||||
file-intent, knowledge-base persistence, subagents, skills, memory) because
|
||||
those middlewares stage or persist "documents" that an anonymous session can
|
||||
never see again -- which produced phantom "I saved it to a file" answers for
|
||||
free users.
|
||||
|
||||
For any other SurfSense capability the model is instructed (via the system
|
||||
prompt built here) to tell the user to create a free account instead of
|
||||
pretending to perform the action.
|
||||
For any other SurfSense capability (including web search) the model is
|
||||
instructed (via the system prompt built here) to tell the user to create a
|
||||
free account instead of pretending to perform the action.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
|
@ -22,7 +22,6 @@ from deepagents.backends import StateBackend
|
|||
from langchain.agents import create_agent
|
||||
from langchain.agents.middleware import (
|
||||
ModelCallLimitMiddleware,
|
||||
ToolCallLimitMiddleware,
|
||||
)
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langgraph.types import Checkpointer
|
||||
|
|
@ -32,7 +31,6 @@ from app.agents.chat.shared.middleware import (
|
|||
RetryAfterMiddleware,
|
||||
create_surfsense_compaction_middleware,
|
||||
)
|
||||
from app.agents.chat.shared.tools.web_search import create_web_search_tool
|
||||
|
||||
# Cap how much of an uploaded document we inline into the system prompt. The
|
||||
# upload endpoint allows files up to several MB, but the doc is re-sent on
|
||||
|
|
@ -77,25 +75,26 @@ def build_anonymous_system_prompt(anon_doc: dict[str, Any] | None = None) -> str
|
|||
"## How to help\n"
|
||||
"- Answer the user's questions directly and conversationally. You are "
|
||||
"a straightforward question-and-answer assistant.\n"
|
||||
"- When a question needs current, real-time, or factual information "
|
||||
"from the internet (news, prices, weather, recent events, live data), "
|
||||
"use the `web_search` tool. Otherwise, answer directly from your own "
|
||||
"knowledge.\n"
|
||||
"- Answer from your own knowledge. You do NOT have web access here, so "
|
||||
"for current, real-time, or fast-changing facts (news, prices, "
|
||||
"weather, recent events, live data) say you can't look them up in the "
|
||||
"free experience and may be out of date, and invite the user to create "
|
||||
"a free account for live web search.\n"
|
||||
"- Be concise, accurate, and helpful. Use Markdown formatting when it "
|
||||
"improves readability."
|
||||
f"{doc_section}\n\n"
|
||||
"## What is not available here\n"
|
||||
"This is the free, no-login experience. You CANNOT save files or "
|
||||
"notes, generate reports, podcasts, resumes, presentations, or images, "
|
||||
"search or build a knowledge base, connect to apps (Gmail, Google "
|
||||
"Drive, Notion, Slack, Calendar, Discord, and similar), set up "
|
||||
"This is the free, no-login experience. You CANNOT search the web, save "
|
||||
"files or notes, generate reports, podcasts, resumes, presentations, or "
|
||||
"images, search or build a knowledge base, connect to apps (Gmail, "
|
||||
"Google Drive, Notion, Slack, Calendar, Discord, and similar), set up "
|
||||
"automations, or remember anything across sessions.\n\n"
|
||||
"If the user asks for any of these, do NOT pretend to do them and "
|
||||
"never claim you saved, created, or stored anything. Instead, briefly "
|
||||
"let them know the feature requires a free SurfSense account and "
|
||||
"invite them to create one at https://www.surfsense.com. Then offer to "
|
||||
"help with what you can do here (answering questions and searching the "
|
||||
"web)."
|
||||
"help with what you can do here (answering questions from your own "
|
||||
"knowledge and about any uploaded document)."
|
||||
)
|
||||
|
||||
|
||||
|
|
@ -105,14 +104,13 @@ async def create_anonymous_chat_agent(
|
|||
checkpointer: Checkpointer,
|
||||
anon_session_id: str | None = None,
|
||||
anon_doc: dict[str, Any] | None = None,
|
||||
enable_web_search: bool = True,
|
||||
):
|
||||
"""Create a minimal Q/A agent for anonymous / free chat.
|
||||
|
||||
Unlike :func:`create_surfsense_deep_agent`, this agent has no filesystem,
|
||||
file-intent, knowledge-base persistence, subagent, skills, or memory
|
||||
middleware. Its only tool is ``web_search`` (when ``enable_web_search`` is
|
||||
True), and any uploaded document is injected into the system prompt as
|
||||
middleware -- and no tools at all. It answers purely from the model's own
|
||||
knowledge; any uploaded document is injected into the system prompt as
|
||||
read-only context.
|
||||
|
||||
Args:
|
||||
|
|
@ -120,36 +118,23 @@ async def create_anonymous_chat_agent(
|
|||
checkpointer: LangGraph checkpointer for the ephemeral anon thread.
|
||||
anon_session_id: Anonymous session id (used only for telemetry/metadata).
|
||||
anon_doc: Optional ``{"title", "content"}`` for an uploaded document.
|
||||
enable_web_search: When False, the agent runs as a pure LLM with no
|
||||
tools (used when the user toggles web search off).
|
||||
"""
|
||||
tools = (
|
||||
[create_web_search_tool(workspace_id=None, available_connectors=None)]
|
||||
if enable_web_search
|
||||
else []
|
||||
)
|
||||
|
||||
# Reliability-only middleware. Nothing here touches the database or
|
||||
# filesystem: call limits guard against loops, compaction summarises long
|
||||
# histories into in-graph state, and retry handles provider rate limits.
|
||||
# filesystem: the call limit guards against loops, compaction summarises
|
||||
# long histories into in-graph state, and retry handles provider rate
|
||||
# limits.
|
||||
middleware: list[Any] = [
|
||||
ModelCallLimitMiddleware(thread_limit=120, run_limit=80, exit_behavior="end"),
|
||||
create_surfsense_compaction_middleware(llm, StateBackend),
|
||||
RetryAfterMiddleware(max_retries=3),
|
||||
]
|
||||
if tools:
|
||||
middleware.append(
|
||||
ToolCallLimitMiddleware(
|
||||
thread_limit=300, run_limit=80, exit_behavior="continue"
|
||||
)
|
||||
)
|
||||
middleware.append(create_surfsense_compaction_middleware(llm, StateBackend))
|
||||
middleware.append(RetryAfterMiddleware(max_retries=3))
|
||||
|
||||
system_prompt = build_anonymous_system_prompt(anon_doc)
|
||||
|
||||
agent = create_agent(
|
||||
llm,
|
||||
system_prompt=system_prompt,
|
||||
tools=tools,
|
||||
tools=[],
|
||||
middleware=middleware,
|
||||
context_schema=SurfSenseContextSchema,
|
||||
checkpointer=checkpointer,
|
||||
|
|
|
|||
|
|
@ -2,27 +2,32 @@
|
|||
|
||||
from __future__ import annotations
|
||||
|
||||
# Connected apps (hosted MCP + interim-native Gmail/Calendar) all route to the
|
||||
# single ``mcp_discovery`` subagent. File connectors stay native (they enrich
|
||||
# the knowledge base). Deprecated connectors (Discord/Teams/Luma) are omitted:
|
||||
# they have no agent subagent, so their rows produce no tools.
|
||||
CONNECTOR_TYPE_TO_CONNECTOR_AGENT_MAPS: dict[str, str] = {
|
||||
"GOOGLE_GMAIL_CONNECTOR": "gmail",
|
||||
"COMPOSIO_GMAIL_CONNECTOR": "gmail",
|
||||
"GOOGLE_CALENDAR_CONNECTOR": "calendar",
|
||||
"COMPOSIO_GOOGLE_CALENDAR_CONNECTOR": "calendar",
|
||||
"DISCORD_CONNECTOR": "discord",
|
||||
"TEAMS_CONNECTOR": "teams",
|
||||
"LUMA_CONNECTOR": "luma",
|
||||
"LINEAR_CONNECTOR": "linear",
|
||||
"JIRA_CONNECTOR": "jira",
|
||||
"CLICKUP_CONNECTOR": "clickup",
|
||||
"SLACK_CONNECTOR": "slack",
|
||||
"AIRTABLE_CONNECTOR": "airtable",
|
||||
"NOTION_CONNECTOR": "notion",
|
||||
"CONFLUENCE_CONNECTOR": "confluence",
|
||||
"GOOGLE_GMAIL_CONNECTOR": "mcp_discovery",
|
||||
"COMPOSIO_GMAIL_CONNECTOR": "mcp_discovery",
|
||||
"GOOGLE_CALENDAR_CONNECTOR": "mcp_discovery",
|
||||
"COMPOSIO_GOOGLE_CALENDAR_CONNECTOR": "mcp_discovery",
|
||||
"LINEAR_CONNECTOR": "mcp_discovery",
|
||||
"JIRA_CONNECTOR": "mcp_discovery",
|
||||
"CLICKUP_CONNECTOR": "mcp_discovery",
|
||||
"SLACK_CONNECTOR": "mcp_discovery",
|
||||
"AIRTABLE_CONNECTOR": "mcp_discovery",
|
||||
"NOTION_CONNECTOR": "mcp_discovery",
|
||||
"CONFLUENCE_CONNECTOR": "mcp_discovery",
|
||||
"MCP_CONNECTOR": "mcp_discovery",
|
||||
"GOOGLE_DRIVE_CONNECTOR": "google_drive",
|
||||
"COMPOSIO_GOOGLE_DRIVE_CONNECTOR": "google_drive",
|
||||
"DROPBOX_CONNECTOR": "dropbox",
|
||||
"ONEDRIVE_CONNECTOR": "onedrive",
|
||||
}
|
||||
|
||||
# ``mcp_discovery`` is gated any-of: present iff the workspace has at least one
|
||||
# connected app. Tokens are searchable-type strings (Composio Gmail/Calendar
|
||||
# map to the GOOGLE_* tokens in connector_searchable_types).
|
||||
SUBAGENT_TO_REQUIRED_CONNECTOR_MAP: dict[str, frozenset[str]] = {
|
||||
"deliverables": frozenset(),
|
||||
"knowledge_base": frozenset(),
|
||||
|
|
@ -31,19 +36,40 @@ SUBAGENT_TO_REQUIRED_CONNECTOR_MAP: dict[str, frozenset[str]] = {
|
|||
"google_maps": frozenset(),
|
||||
"google_search": frozenset(),
|
||||
"reddit": frozenset(),
|
||||
"airtable": frozenset({"AIRTABLE_CONNECTOR"}),
|
||||
"calendar": frozenset({"GOOGLE_CALENDAR_CONNECTOR"}),
|
||||
"clickup": frozenset({"CLICKUP_CONNECTOR"}),
|
||||
"confluence": frozenset({"CONFLUENCE_CONNECTOR"}),
|
||||
"discord": frozenset({"DISCORD_CONNECTOR"}),
|
||||
"mcp_discovery": frozenset(
|
||||
{
|
||||
"SLACK_CONNECTOR",
|
||||
"JIRA_CONNECTOR",
|
||||
"LINEAR_CONNECTOR",
|
||||
"CLICKUP_CONNECTOR",
|
||||
"AIRTABLE_CONNECTOR",
|
||||
"NOTION_CONNECTOR",
|
||||
"CONFLUENCE_CONNECTOR",
|
||||
"GOOGLE_GMAIL_CONNECTOR",
|
||||
"GOOGLE_CALENDAR_CONNECTOR",
|
||||
"MCP_CONNECTOR",
|
||||
}
|
||||
),
|
||||
"dropbox": frozenset({"DROPBOX_FILE"}),
|
||||
"gmail": frozenset({"GOOGLE_GMAIL_CONNECTOR"}),
|
||||
"google_drive": frozenset({"GOOGLE_DRIVE_FILE"}),
|
||||
"jira": frozenset({"JIRA_CONNECTOR"}),
|
||||
"linear": frozenset({"LINEAR_CONNECTOR"}),
|
||||
"luma": frozenset({"LUMA_CONNECTOR"}),
|
||||
"notion": frozenset({"NOTION_CONNECTOR"}),
|
||||
"onedrive": frozenset({"ONEDRIVE_FILE"}),
|
||||
"slack": frozenset({"SLACK_CONNECTOR"}),
|
||||
"teams": frozenset({"TEAMS_CONNECTOR"}),
|
||||
}
|
||||
|
||||
# Old per-connector subagent names, kept working for checkpoint resume: a
|
||||
# ``task(subagent_type="gmail")`` paused before the MCP consolidation resolves
|
||||
# to the consolidated ``mcp_discovery`` subagent instead of hard-failing
|
||||
# "subagent does not exist". New routing never emits these names.
|
||||
LEGACY_SUBAGENT_ALIASES: dict[str, str] = {
|
||||
"gmail": "mcp_discovery",
|
||||
"calendar": "mcp_discovery",
|
||||
"linear": "mcp_discovery",
|
||||
"jira": "mcp_discovery",
|
||||
"clickup": "mcp_discovery",
|
||||
"slack": "mcp_discovery",
|
||||
"airtable": "mcp_discovery",
|
||||
"notion": "mcp_discovery",
|
||||
"confluence": "mcp_discovery",
|
||||
"discord": "mcp_discovery",
|
||||
"teams": "mcp_discovery",
|
||||
"luma": "mcp_discovery",
|
||||
}
|
||||
|
|
|
|||
|
|
@ -23,6 +23,7 @@ from langchain_core.tools import StructuredTool
|
|||
from langgraph.errors import GraphInterrupt
|
||||
from langgraph.types import Command, Interrupt
|
||||
|
||||
from app.agents.chat.multi_agent_chat.constants import LEGACY_SUBAGENT_ALIASES
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.invocation import (
|
||||
EXCLUDED_STATE_KEYS,
|
||||
subagent_invoke_config,
|
||||
|
|
@ -157,6 +158,26 @@ def build_task_tool_with_parent_config(
|
|||
case a trivial dict-backed resolver is used.
|
||||
"""
|
||||
subagent_names: set[str] = {spec["name"] for spec in subagents}
|
||||
|
||||
def _canonical_subagent_type(subagent_type: str) -> str:
|
||||
"""Resolve a legacy connector subagent name to its consolidated route.
|
||||
|
||||
Only rewrites when the requested name is unavailable but its alias is
|
||||
(checkpoint resume of a pre-consolidation ``task(...)`` call). Current
|
||||
routing never emits legacy names, so live traffic is untouched.
|
||||
"""
|
||||
if subagent_type in subagent_names:
|
||||
return subagent_type
|
||||
alias = LEGACY_SUBAGENT_ALIASES.get(subagent_type)
|
||||
if alias is not None and alias in subagent_names:
|
||||
logger.info(
|
||||
"[hitl_route] aliasing legacy subagent %r -> %r",
|
||||
subagent_type,
|
||||
alias,
|
||||
)
|
||||
return alias
|
||||
return subagent_type
|
||||
|
||||
if resolve_subagent is None:
|
||||
_eager_graphs: dict[str, Runnable] = {
|
||||
spec["name"]: spec["runnable"] for spec in subagents if "runnable" in spec
|
||||
|
|
@ -482,6 +503,7 @@ def build_task_tool_with_parent_config(
|
|||
batched HITL is intentionally out of scope.
|
||||
"""
|
||||
async with semaphore:
|
||||
subagent_type = _canonical_subagent_type(subagent_type)
|
||||
if subagent_type not in subagent_names:
|
||||
allowed_types = ", ".join([f"`{k}`" for k in subagent_names])
|
||||
return (
|
||||
|
|
@ -658,6 +680,7 @@ def build_task_tool_with_parent_config(
|
|||
"task: must provide either single-mode (`description`+`subagent_type`) "
|
||||
"or batch-mode (`tasks`)."
|
||||
)
|
||||
subagent_type = _canonical_subagent_type(subagent_type)
|
||||
if subagent_type not in subagent_names:
|
||||
allowed_types = ", ".join([f"`{k}`" for k in subagent_names])
|
||||
return (
|
||||
|
|
@ -867,6 +890,7 @@ def build_task_tool_with_parent_config(
|
|||
subagent_type,
|
||||
runtime.tool_call_id,
|
||||
)
|
||||
subagent_type = _canonical_subagent_type(subagent_type)
|
||||
if subagent_type not in subagent_names:
|
||||
allowed_types = ", ".join([f"`{k}`" for k in subagent_names])
|
||||
return (
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
This is agent-agnostic infrastructure shared by every agent factory (single-
|
||||
and multi-agent). It translates the connectors a workspace has enabled into
|
||||
the set of searchable type strings that pre-search middleware and ``web_search``
|
||||
understand, and always layers in the document types that exist independently of
|
||||
any connector (uploads, notes, extension captures, YouTube).
|
||||
the set of searchable type strings that pre-search middleware understands, and
|
||||
always layers in the document types that exist independently of any connector
|
||||
(uploads, notes, extension captures, YouTube).
|
||||
|
||||
It lives in its own module — rather than inside a specific agent factory — so
|
||||
that retiring or moving any single agent never disturbs the others' access to
|
||||
|
|
@ -16,15 +16,8 @@ from __future__ import annotations
|
|||
from typing import Any
|
||||
|
||||
# Maps SearchSourceConnectorType enum values to the searchable document/connector types
|
||||
# used by pre-search middleware and web_search.
|
||||
# Live search connectors (TAVILY_API, LINKUP_API, BAIDU_SEARCH_API) are routed to
|
||||
# the web_search tool; all others are considered local/indexed data.
|
||||
# used by KB pre-search middleware. All entries are local/indexed data.
|
||||
_CONNECTOR_TYPE_TO_SEARCHABLE: dict[str, str] = {
|
||||
# Live search connectors (handled by web_search tool)
|
||||
"TAVILY_API": "TAVILY_API",
|
||||
"LINKUP_API": "LINKUP_API",
|
||||
"BAIDU_SEARCH_API": "BAIDU_SEARCH_API",
|
||||
# Local/indexed connectors (handled by KB pre-search middleware)
|
||||
"SLACK_CONNECTOR": "SLACK_CONNECTOR",
|
||||
"TEAMS_CONNECTOR": "TEAMS_CONNECTOR",
|
||||
"NOTION_CONNECTOR": "NOTION_CONNECTOR",
|
||||
|
|
@ -45,6 +38,9 @@ _CONNECTOR_TYPE_TO_SEARCHABLE: dict[str, str] = {
|
|||
"OBSIDIAN_CONNECTOR": "OBSIDIAN_CONNECTOR",
|
||||
"DROPBOX_CONNECTOR": "DROPBOX_FILE", # Connector type differs from document type
|
||||
"ONEDRIVE_CONNECTOR": "ONEDRIVE_FILE", # Connector type differs from document type
|
||||
# Generic user-defined MCP server: unlocks the mcp_discovery subagent even
|
||||
# in a workspace with no hosted-service connectors.
|
||||
"MCP_CONNECTOR": "MCP_CONNECTOR",
|
||||
# Composio connectors (unified to native document types).
|
||||
# Reverse of NATIVE_TO_LEGACY_DOCTYPE in app.db.
|
||||
"COMPOSIO_GOOGLE_DRIVE_CONNECTOR": "GOOGLE_DRIVE_FILE",
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: kb-research
|
||||
description: Structured approach to finding and synthesizing information from the user's knowledge base
|
||||
allowed-tools: scrape_webpage, read_file, ls_tree, grep, web_search
|
||||
allowed-tools: scrape_webpage, read_file, ls_tree, grep
|
||||
---
|
||||
|
||||
# Knowledge-base research
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: meeting-prep
|
||||
description: Pull together briefing materials before a scheduled meeting
|
||||
allowed-tools: web_search, scrape_webpage, read_file
|
||||
allowed-tools: task, scrape_webpage, read_file
|
||||
---
|
||||
|
||||
# Meeting preparation
|
||||
|
|
@ -12,11 +12,11 @@ The user mentions an upcoming meeting, call, or interview and asks you to "prep"
|
|||
## Output structure
|
||||
Always produce these sections (omit any with no signal — don't pad):
|
||||
|
||||
1. **Attendees & context** — who's in the room, their roles, what they care about. Pull from KB notes about prior interactions; supplement with public profile facts via `web_search` when names or companies are unfamiliar.
|
||||
1. **Attendees & context** — who's in the room, their roles, what they care about. Pull from KB notes about prior interactions; supplement with public profile facts via `task(google_search, ...)` when names or companies are unfamiliar.
|
||||
2. **Open threads** — outstanding action items, unresolved decisions, last-mentioned blockers from prior conversation history.
|
||||
3. **Recent moves** — within the last 30 days: relevant launches, hires, news. Cite KB chunks when present, otherwise external sources.
|
||||
4. **Suggested questions** — 3-5 questions the user could ask, tailored to the open threads and the attendees' likely priorities.
|
||||
|
||||
## Source ordering
|
||||
- Always check the user's KB **first** for prior meeting notes, internal docs, or Slack threads about these attendees.
|
||||
- Only fall back to `web_search` for *publicly verifiable* facts — never to fabricate a participant's preferences or relationships.
|
||||
- Only fall back to `task(google_search, ...)` for *publicly verifiable* facts — never to fabricate a participant's preferences or relationships.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
<citations>
|
||||
Cite with one token: the bracket label `[n]`. Every citable result —
|
||||
`web_search` results and prose from a `task` knowledge_base/research
|
||||
specialist (including the knowledge_base specialist's `[n]`-labelled
|
||||
workspace findings) — already carries `[n]` labels on a single shared count.
|
||||
prose from a `task` knowledge_base/research specialist (including the
|
||||
knowledge_base specialist's `[n]`-labelled workspace findings) — already
|
||||
carries `[n]` labels on a single shared count.
|
||||
Those labels are the only citation you write; the server resolves each one
|
||||
back to its source after the turn.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,23 @@
|
|||
<knowledge_base_first>
|
||||
CRITICAL — ground factual answers in what you actually receive this turn:
|
||||
- the user's knowledge base via `task(knowledge_base, ...)` (your PRIMARY
|
||||
source for anything about their documents, notes, or connected data — the
|
||||
`<workspace_tree>` only lists what exists, so delegate to the specialist to
|
||||
search and read the actual content before answering),
|
||||
source for anything about their own uploaded files, documents, and notes —
|
||||
the `<workspace_tree>` only lists what exists, so delegate to the specialist
|
||||
to search and read the actual content before answering),
|
||||
- injected workspace context (see `<dynamic_context>`),
|
||||
- results from your other tool calls (`web_search`, `scrape_webpage`),
|
||||
- the user's connected apps via `task(mcp_discovery, ...)` (Slack, Jira,
|
||||
Notion, Gmail, Calendar, etc. — live data that is NOT in the knowledge base),
|
||||
- results from your other tool calls (`scrape_webpage`) or the Google Search
|
||||
specialist via `task(google_search, ...)`,
|
||||
- or substantive summaries returned by a `task` specialist you invoked.
|
||||
|
||||
For questions about the user's own workspace, dispatch
|
||||
For questions about the user's own files and notes, dispatch
|
||||
`task(knowledge_base, ...)` first rather than answering from the tree or from
|
||||
memory. The knowledge_base specialist runs hybrid semantic/keyword search and
|
||||
full-document reads, then returns a grounded summary with `[n]` citation
|
||||
labels for you to carry through into your answer.
|
||||
full-document reads over their personal files and notes, then returns a
|
||||
grounded summary with `[n]` citation labels for you to carry into your answer.
|
||||
For anything living in a connected third-party app, use
|
||||
`task(mcp_discovery, ...)` instead — that content is not indexed in the KB.
|
||||
|
||||
Do **not** answer factual or informational questions from general knowledge
|
||||
unless the user explicitly authorises it after you say you couldn't find
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Structured reasoning:
|
|||
- For non-trivial work, `<thinking>` / short `<plan>` before tool calls is fine.
|
||||
|
||||
Professional objectivity:
|
||||
- Accuracy over flattery; verify with **web_search**, **scrape_webpage**, or **task** when unsure — don’t invent connector access.
|
||||
- Accuracy over flattery; verify with **scrape_webpage** or **task** (e.g. `task(google_search, …)` for public facts) when unsure — don’t invent connector access.
|
||||
|
||||
Task management:
|
||||
- For 3+ steps, use todo tooling; update statuses promptly.
|
||||
|
|
|
|||
|
|
@ -16,6 +16,6 @@ Output style:
|
|||
Tool calls:
|
||||
- Parallelise independent calls in one turn.
|
||||
- For SurfSense-product questions, point the user to https://www.surfsense.com/docs;
|
||||
use **web_search** / **scrape_webpage** for fresh public facts; integrations and
|
||||
use **task(google_search, …)** / **scrape_webpage** for fresh public facts; integrations and
|
||||
heavy workflows → **task**.
|
||||
</provider_hints>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,6 @@ You have two execution channels. Pick the one that owns the work — never
|
|||
simulate one with the other.
|
||||
|
||||
### 1. Direct tools (you call them yourself)
|
||||
- `web_search` — search the public web (anything outside the workspace KB).
|
||||
- `scrape_webpage` — fetch the body of a specific public URL.
|
||||
- `update_memory` — curate persistent memory (see `<memory_protocol>`).
|
||||
- `write_todos` — maintain a structured plan when the turn series spans
|
||||
|
|
@ -64,13 +63,16 @@ user: "Save these meeting notes to my KB: …"
|
|||
|
||||
<example>
|
||||
user: "What did Maya say about the Q2 roadmap in Slack last week?"
|
||||
→ task(slack, "Find messages from Maya about the Q2 roadmap from the past
|
||||
week. Return the most relevant quotes with channel and timestamp.")
|
||||
→ task(mcp_discovery, "In Slack, find messages from Maya about the Q2 roadmap
|
||||
from the past week. Return the most relevant quotes with channel and
|
||||
timestamp.")
|
||||
</example>
|
||||
|
||||
<example>
|
||||
user: "What's the current USD/INR rate?"
|
||||
→ web_search(query="current USD to INR exchange rate")
|
||||
→ Public web lookup — delegate to the Google Search specialist:
|
||||
task(google_search, "Search Google for the current USD to INR exchange
|
||||
rate and return the rate with its source URL.")
|
||||
</example>
|
||||
|
||||
<example>
|
||||
|
|
@ -82,15 +84,16 @@ user: "Find my Q2 roadmap and summarise the milestones."
|
|||
|
||||
<example>
|
||||
user: "Create a ClickUp ticket and a Linear ticket for the new feature flag."
|
||||
→ Independent work — call both specialists in parallel:
|
||||
→ Independent work, same specialist (connected apps) with non-overlapping
|
||||
scopes — call it twice in parallel, naming the target app in each prompt:
|
||||
write_todos([
|
||||
{content: "Create ClickUp ticket for feature flag rollout", status: "in_progress"},
|
||||
{content: "Create Linear ticket for feature flag rollout", status: "in_progress"},
|
||||
])
|
||||
task(clickup, "Create a ClickUp ticket titled 'Feature flag rollout'
|
||||
in the default list. Description: <…>. Tell me the ticket URL.")
|
||||
task(linear, "Create a Linear ticket titled 'Feature flag rollout'
|
||||
in the default team. Description: <…>. Tell me the ticket URL.")
|
||||
task(mcp_discovery, "In ClickUp, create a ticket titled 'Feature flag
|
||||
rollout' in the default list. Description: <…>. Tell me the ticket URL.")
|
||||
task(mcp_discovery, "In Linear, create a ticket titled 'Feature flag
|
||||
rollout' in the default team. Description: <…>. Tell me the ticket URL.")
|
||||
</example>
|
||||
|
||||
<example>
|
||||
|
|
@ -100,24 +103,25 @@ user: "Find my Q2 roadmap doc in the KB and email a summary to Maya."
|
|||
task(knowledge_base, "Find the Q2 roadmap document under /documents
|
||||
and return its full text plus a 3-bullet summary.")
|
||||
Next turn (with the returned summary in hand):
|
||||
task(gmail, "Send an email to Maya with subject 'Q2 roadmap summary'
|
||||
and the following body: <summary returned by knowledge_base>.")
|
||||
task(mcp_discovery, "In Gmail, send an email to Maya with subject 'Q2
|
||||
roadmap summary' and the following body: <summary returned by
|
||||
knowledge_base>.")
|
||||
</example>
|
||||
|
||||
<example>
|
||||
user: "Create issues in Linear for each of these five bugs: <list>"
|
||||
→ Many-shot independent fanout — use the batch shape:
|
||||
task(tasks=[
|
||||
{subagent_type: "linear", description: "Create a Linear issue titled
|
||||
'<bug 1 title>' with body '<bug 1 body>'. Return the issue URL."},
|
||||
{subagent_type: "linear", description: "Create a Linear issue titled
|
||||
'<bug 2 title>' with body '<bug 2 body>'. Return the issue URL."},
|
||||
{subagent_type: "linear", description: "Create a Linear issue titled
|
||||
'<bug 3 title>' with body '<bug 3 body>'. Return the issue URL."},
|
||||
{subagent_type: "linear", description: "Create a Linear issue titled
|
||||
'<bug 4 title>' with body '<bug 4 body>'. Return the issue URL."},
|
||||
{subagent_type: "linear", description: "Create a Linear issue titled
|
||||
'<bug 5 title>' with body '<bug 5 body>'. Return the issue URL."},
|
||||
{subagent_type: "mcp_discovery", description: "In Linear, create an issue
|
||||
titled '<bug 1 title>' with body '<bug 1 body>'. Return the issue URL."},
|
||||
{subagent_type: "mcp_discovery", description: "In Linear, create an issue
|
||||
titled '<bug 2 title>' with body '<bug 2 body>'. Return the issue URL."},
|
||||
{subagent_type: "mcp_discovery", description: "In Linear, create an issue
|
||||
titled '<bug 3 title>' with body '<bug 3 body>'. Return the issue URL."},
|
||||
{subagent_type: "mcp_discovery", description: "In Linear, create an issue
|
||||
titled '<bug 4 title>' with body '<bug 4 body>'. Return the issue URL."},
|
||||
{subagent_type: "mcp_discovery", description: "In Linear, create an issue
|
||||
titled '<bug 5 title>' with body '<bug 5 body>'. Return the issue URL."},
|
||||
])
|
||||
Read back the `[task 0]`…`[task 4]` blocks in the combined ToolMessage and
|
||||
verify each via its Receipt's `verifiable_url` per the `<verification>`
|
||||
|
|
@ -154,16 +158,17 @@ user: "Make a 30-second podcast of this conversation."
|
|||
<example>
|
||||
user: "Post the launch announcement to #general and let me know when it's up."
|
||||
→ Mutating subagent + user wants external confirmation. Apply the
|
||||
`<verification>` teaching: the slack subagent's reply is a self-report;
|
||||
check its `evidence.receipts` for a Receipt with `status="success"` and
|
||||
a `verifiable_url`, then fetch that URL to confirm before reporting back.
|
||||
`<verification>` teaching: the connected-apps subagent's reply is a
|
||||
self-report; check its `evidence.receipts` for a Receipt with
|
||||
`status="success"` and a `verifiable_url`, then fetch that URL to confirm
|
||||
before reporting back.
|
||||
This turn:
|
||||
task(slack, "Post '<launch announcement text>' to #general.
|
||||
Return the message permalink.")
|
||||
task(mcp_discovery, "In Slack, post '<launch announcement text>' to
|
||||
#general. Return the message permalink.")
|
||||
Next turn (with the receipt's `verifiable_url` in hand):
|
||||
scrape_webpage(url=<verifiable_url from slack receipt>)
|
||||
scrape_webpage(url=<verifiable_url from the receipt>)
|
||||
→ confirm the post is live, then tell the user it's up with the URL.
|
||||
If the slack reply has NO Receipt with `status="success"`, treat it as a
|
||||
If the reply has NO Receipt with `status="success"`, treat it as a
|
||||
silent failure: surface the error verbatim, do not retry.
|
||||
</example>
|
||||
</routing>
|
||||
|
|
|
|||
|
|
@ -7,9 +7,9 @@ user: "Save these meeting notes to my KB: …"
|
|||
|
||||
<example>
|
||||
user: "What did Maya say about the Q2 roadmap in Slack last week?"
|
||||
→ task(subagent_type="slack", description="Find messages from Maya about
|
||||
the Q2 roadmap from the past week. Return the most relevant quotes with
|
||||
channel and timestamp.")
|
||||
→ task(subagent_type="mcp_discovery", description="In Slack, find messages
|
||||
from Maya about the Q2 roadmap from the past week. Return the most relevant
|
||||
quotes with channel and timestamp.")
|
||||
</example>
|
||||
|
||||
<example>
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
"""``web_search`` — description + few-shot examples."""
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
- `web_search` — Search the public web.
|
||||
- Use whenever an answer benefits from external sources — current events,
|
||||
prices, weather, news, technical references, definitions, background
|
||||
facts, anything outside SurfSense docs and the workspace KB. Reach for
|
||||
it whenever freshness matters or you'd otherwise guess from memory.
|
||||
- Don't refuse with "I lack network access" — call the tool.
|
||||
- Returns a `<web_results>` block: each result is labelled `[n]`. Cite a
|
||||
result by writing that `[n]` after the statement it supports (when
|
||||
citations are enabled) — do not hand-write the URL as a markdown link.
|
||||
- If results are thin, say so and offer to refine the query.
|
||||
- Args: `query`, `top_k` (default 10, max 50).
|
||||
- Follow up with `scrape_webpage` on the best URL when snippets are too
|
||||
shallow.
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
<example>
|
||||
user: "What's the current USD to INR exchange rate?"
|
||||
→ web_search(query="current USD to INR exchange rate")
|
||||
(Answer from snippets; scrape a top URL if needed.)
|
||||
</example>
|
||||
|
||||
<example>
|
||||
user: "What's the latest news about AI?"
|
||||
→ web_search(query="latest AI news today")
|
||||
</example>
|
||||
|
||||
<example>
|
||||
user: "What's the weather in New York?"
|
||||
→ web_search(query="weather New York today")
|
||||
</example>
|
||||
|
|
@ -6,7 +6,6 @@ Connector integrations, MCP, deliverables, etc. are delegated via ``task`` subag
|
|||
from __future__ import annotations
|
||||
|
||||
MAIN_AGENT_SURFSENSE_TOOL_NAMES_ORDERED: tuple[str, ...] = (
|
||||
"web_search",
|
||||
"scrape_webpage",
|
||||
"update_memory",
|
||||
"create_automation",
|
||||
|
|
|
|||
|
|
@ -21,7 +21,6 @@ from typing import Any
|
|||
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.shared.tools.web_search import create_web_search_tool
|
||||
from app.db import ChatVisibility
|
||||
|
||||
from .scrape_webpage import create_scrape_webpage_tool
|
||||
|
|
@ -35,13 +34,6 @@ def _build_scrape_webpage_tool(_deps: dict[str, Any]) -> BaseTool:
|
|||
return create_scrape_webpage_tool()
|
||||
|
||||
|
||||
def _build_web_search_tool(deps: dict[str, Any]) -> BaseTool:
|
||||
return create_web_search_tool(
|
||||
workspace_id=deps.get("workspace_id"),
|
||||
available_connectors=deps.get("available_connectors"),
|
||||
)
|
||||
|
||||
|
||||
def _build_create_automation_tool(deps: dict[str, Any]) -> BaseTool:
|
||||
# Deferred import: the automation package is a sibling under ``main_agent``
|
||||
# and is only needed at build time, mirroring the shared registry's
|
||||
|
|
@ -71,13 +63,12 @@ def _build_update_memory_tool(deps: dict[str, Any]) -> BaseTool:
|
|||
|
||||
|
||||
# Ordered to match the historical main-agent binding order:
|
||||
# scrape_webpage, web_search, create_automation, update_memory.
|
||||
# scrape_webpage, create_automation, update_memory.
|
||||
# Each entry is ``(factory, required_dependency_names)``.
|
||||
_MAIN_AGENT_TOOL_FACTORIES: dict[
|
||||
str, tuple[Callable[[dict[str, Any]], BaseTool], tuple[str, ...]]
|
||||
] = {
|
||||
"scrape_webpage": (_build_scrape_webpage_tool, ()),
|
||||
"web_search": (_build_web_search_tool, ()),
|
||||
"create_automation": (
|
||||
_build_create_automation_tool,
|
||||
("workspace_id", "user_id", "llm"),
|
||||
|
|
|
|||
|
|
@ -1,9 +1,8 @@
|
|||
"""Render citable documents for the model: one shape for search, read, and web.
|
||||
"""Render citable documents for the model: one shape for search and read.
|
||||
|
||||
``render_document`` emits one ``<document title=… source=… view="excerpt|full">``
|
||||
block whose passages carry server-assigned ``[n]`` labels. ``render_search_context``
|
||||
wraps KB excerpt blocks in ``<retrieved_context>``; ``render_web_results`` wraps web
|
||||
excerpt blocks in ``<web_results>``. Both cite with the same ``[n]`` spine.
|
||||
wraps KB excerpt blocks in ``<retrieved_context>`` and cites with the ``[n]`` spine.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
|
@ -12,7 +11,6 @@ from .document import render_document
|
|||
from .models import DocumentView, RenderableDocument, RenderablePassage
|
||||
from .search_context import render_search_context
|
||||
from .source_label import source_label
|
||||
from .web_results import render_web_results
|
||||
|
||||
__all__ = [
|
||||
"DocumentView",
|
||||
|
|
@ -20,6 +18,5 @@ __all__ = [
|
|||
"RenderablePassage",
|
||||
"render_document",
|
||||
"render_search_context",
|
||||
"render_web_results",
|
||||
"source_label",
|
||||
]
|
||||
|
|
|
|||
|
|
@ -1,46 +0,0 @@
|
|||
"""Wrap live web-search results in a ``<web_results>`` block.
|
||||
|
||||
Each result renders through the shared ``render_document`` (excerpt view), so a
|
||||
web result is cited with ``[n]`` exactly like a knowledge-base passage. Only the
|
||||
container and header differ — they tell the model these came from the public web,
|
||||
not the user's workspace.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.citations import CitationRegistry
|
||||
|
||||
from .document import render_document
|
||||
from .models import RenderableDocument
|
||||
|
||||
_HEADER = (
|
||||
"These are live results from a public web search for this query. Each\n"
|
||||
"<document> below is one result in excerpt view; cite a result with its [n]\n"
|
||||
"after the statement it supports. Scrape the URL for full context before\n"
|
||||
"making a definitive claim from a snippet."
|
||||
)
|
||||
|
||||
|
||||
def render_web_results(
|
||||
documents: list[RenderableDocument],
|
||||
registry: CitationRegistry,
|
||||
) -> str | None:
|
||||
"""Render web results as excerpt blocks inside ``<web_results>``.
|
||||
|
||||
Returns ``None`` when no result has content to show, so the caller can skip
|
||||
the block. Mutates ``registry`` (find-or-create), so a URL seen again keeps
|
||||
its original ``[n]``.
|
||||
"""
|
||||
blocks = [
|
||||
block
|
||||
for document in documents
|
||||
if (block := render_document(document, view="excerpt", registry=registry))
|
||||
is not None
|
||||
]
|
||||
if not blocks:
|
||||
return None
|
||||
|
||||
return "<web_results>\n" + _HEADER + "\n" + "\n".join(blocks) + "\n</web_results>"
|
||||
|
||||
|
||||
__all__ = ["render_web_results"]
|
||||
|
|
@ -33,10 +33,13 @@ from __future__ import annotations
|
|||
|
||||
from typing import Any, Literal, TypedDict
|
||||
|
||||
# Subagent that emitted this receipt.
|
||||
# Subagent that emitted this receipt. ``mcp_discovery`` is the current
|
||||
# connected-apps route; the per-connector literals below it are retained so
|
||||
# historical receipts (persisted in old checkpoints) still type-check.
|
||||
ReceiptRoute = Literal[
|
||||
"deliverables",
|
||||
"knowledge_base",
|
||||
"mcp_discovery",
|
||||
"notion",
|
||||
"slack",
|
||||
"gmail",
|
||||
|
|
|
|||
|
|
@ -1,18 +1,17 @@
|
|||
"""Knowledge-base retrieval: hybrid search rendered as citable evidence.
|
||||
|
||||
Public surface is the service (``search_knowledge_base_context``) and its input
|
||||
value object (``SearchScope``); the rest are building blocks.
|
||||
Public surface is ``build_context`` (rerank → adapt → render) and the
|
||||
``SearchScope`` input value object; the rest are building blocks.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from .models import ChunkHit, DocumentHit, SearchScope
|
||||
from .service import build_context, search_knowledge_base_context
|
||||
from .service import build_context
|
||||
|
||||
__all__ = [
|
||||
"ChunkHit",
|
||||
"DocumentHit",
|
||||
"SearchScope",
|
||||
"build_context",
|
||||
"search_knowledge_base_context",
|
||||
]
|
||||
|
|
|
|||
|
|
@ -1,54 +1,27 @@
|
|||
"""Search the knowledge base and render it as model-facing ``<retrieved_context>``.
|
||||
"""Render knowledge-base hits as model-facing ``<retrieved_context>``.
|
||||
|
||||
The retrieval spine end to end: hybrid search → rerank → adapt → render, with
|
||||
each shown passage registered for ``[n]`` citation along the way.
|
||||
The tail of the retrieval spine: rerank → adapt → render, registering each
|
||||
shown passage for ``[n]`` citation. Hybrid search itself lives in
|
||||
``hybrid_search``; callers (the ``search_knowledge_base`` tool) pass its hits
|
||||
straight into :func:`build_context`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.citations import CitationRegistry
|
||||
from app.agents.chat.multi_agent_chat.shared.document_render import (
|
||||
render_search_context,
|
||||
)
|
||||
|
||||
from .adapter import to_renderable_document
|
||||
from .hybrid_search import search_chunks
|
||||
from .models import DocumentHit, SearchScope
|
||||
from .models import DocumentHit
|
||||
from .reranking import rerank_hits
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from app.services.reranker_service import RerankerService
|
||||
|
||||
_DEFAULT_TOP_K = 10
|
||||
|
||||
|
||||
async def search_knowledge_base_context(
|
||||
db_session: AsyncSession,
|
||||
*,
|
||||
workspace_id: int,
|
||||
query: str,
|
||||
registry: CitationRegistry,
|
||||
scope: SearchScope | None = None,
|
||||
reranker: RerankerService | None = None,
|
||||
top_k: int = _DEFAULT_TOP_K,
|
||||
) -> str | None:
|
||||
"""Retrieve KB evidence for ``query`` and render it, registering each ``[n]``.
|
||||
|
||||
Returns ``None`` when nothing matched, so the caller can skip the block.
|
||||
"""
|
||||
hits = await search_chunks(
|
||||
db_session,
|
||||
workspace_id=workspace_id,
|
||||
query=query,
|
||||
scope=scope or SearchScope(),
|
||||
top_k=top_k,
|
||||
)
|
||||
return build_context(query, hits, registry, reranker=reranker)
|
||||
|
||||
|
||||
def build_context(
|
||||
query: str,
|
||||
|
|
@ -63,4 +36,4 @@ def build_context(
|
|||
return render_search_context(documents, registry)
|
||||
|
||||
|
||||
__all__ = ["build_context", "search_knowledge_base_context"]
|
||||
__all__ = ["build_context"]
|
||||
|
|
|
|||
|
|
@ -68,10 +68,6 @@ TOOL_CATALOG: list[ToolMetadata] = [
|
|||
name="scrape_webpage",
|
||||
description="Scrape and extract the main content from a webpage",
|
||||
),
|
||||
ToolMetadata(
|
||||
name="web_search",
|
||||
description="Search the web for real-time information using configured search engines",
|
||||
),
|
||||
ToolMetadata(
|
||||
name="create_automation",
|
||||
description="Draft an automation from an NL intent; user approves the card; tool saves",
|
||||
|
|
|
|||
|
|
@ -1,2 +1,2 @@
|
|||
Google Search specialist: runs Google searches and returns structured SERP data — organic results (title, URL, description), related queries, people-also-ask, and any AI overview. Searches by plain query (optionally scoped to a country/language or restricted to a single site) or scrapes a Google Search URL as-is, and can page deeper with max_pages_per_query. Also compares fresh search results against earlier findings in this chat.
|
||||
Use whenever the task is to find pages or sources on the open web via Google, discover which sites rank for a topic, or gather a list of result URLs to hand off for crawling. Triggers include "search Google for X", "find websites/pages about X", "who ranks for X", "top results for X", "find X's website", and comparisons against earlier search results in this chat. Not for reading a specific page's content (use the web crawling specialist), Google Maps places (use the Google Maps specialist), or YouTube (use the YouTube specialist).
|
||||
This is the sole path for public web search: use it for any real-time or public-fact lookup (current events, news, prices, weather, exchange rates, live data) as well as to find pages or sources on the open web via Google, discover which sites rank for a topic, or gather a list of result URLs to hand off for crawling. Triggers include "search Google for X", "what's the current X", "latest news on X", "find websites/pages about X", "who ranks for X", "top results for X", "find X's website", and comparisons against earlier search results in this chat. Not for reading a specific page's content (use the web crawling specialist), Google Maps places (use the Google Maps specialist), or YouTube (use the YouTube specialist).
|
||||
|
|
|
|||
|
|
@ -38,13 +38,15 @@ _DEFAULT_TOP_K = 5
|
|||
_MAX_TOP_K = 20
|
||||
|
||||
_TOOL_DESCRIPTION = (
|
||||
"Search the user's knowledge base (their indexed documents, files, and "
|
||||
"connector content) for passages relevant to a query, using hybrid "
|
||||
"semantic + keyword retrieval.\n\n"
|
||||
"Search the user's knowledge base — their own uploaded files, documents, "
|
||||
"and notes — for passages relevant to a query, using hybrid semantic + "
|
||||
"keyword retrieval.\n\n"
|
||||
"Use this FIRST to ground any factual or informational answer about the "
|
||||
"user's own documents, notes, or connected sources. It returns a "
|
||||
"<retrieved_context> block: each matched passage is labelled [n]. Cite a "
|
||||
"passage by writing that [n] after the statement it supports.\n\n"
|
||||
"user's personal files and notes. It returns a <retrieved_context> block: "
|
||||
"each matched passage is labelled [n]. Cite a passage by writing that [n] "
|
||||
"after the statement it supports.\n\n"
|
||||
"This searches only the user's stored files and notes — live data in "
|
||||
"connected apps (Slack, Jira, Notion, Gmail, etc.) is not indexed here.\n\n"
|
||||
"Write a focused, specific query containing the concrete entities, "
|
||||
"acronyms, people, projects, or terms you are looking for."
|
||||
)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
"""``mcp_discovery`` builtin subagent: the user's connected apps via MCP.
|
||||
|
||||
Consolidates every MCP-backed connector (Slack, Jira, Linear, ClickUp,
|
||||
Airtable, Notion, Confluence, generic user MCP servers) plus the interim
|
||||
native Gmail/Calendar tools behind a single subagent. Tools are injected
|
||||
directly (opencode/hermes pattern) so the tool-name-keyed permission and
|
||||
"Always Allow" systems keep working unchanged.
|
||||
"""
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
"""``mcp_discovery`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Consolidates every MCP-backed connector plus interim native Gmail/Calendar
|
||||
tools. The permission ruleset is derived from the runtime tool set (not a
|
||||
static constant) because the MCP tool roster is per-user.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.permissions import Rule, Ruleset
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, build_ruleset, load_tools
|
||||
|
||||
|
||||
def _augment_allowlist_for_collision_prefixes(
|
||||
dependencies: dict[str, Any],
|
||||
tools: list[BaseTool],
|
||||
) -> dict[str, Any]:
|
||||
"""Keep "Always Allow" working for tools that got collision-prefixed.
|
||||
|
||||
A tool trusted under its bare name (``search``) can later be renamed to
|
||||
``notion_5_search`` once a second app also exposes ``search`` (Phase 2b
|
||||
collision resolution). The user's persisted allow-rule still keys on the
|
||||
bare name, so we add an alias allow-rule for the new exposed name when the
|
||||
original is already trusted. Returns ``dependencies`` unchanged when there
|
||||
is nothing to do.
|
||||
"""
|
||||
by_subagent = dependencies.get("user_allowlist_by_subagent") or {}
|
||||
existing = by_subagent.get(NAME)
|
||||
if not isinstance(existing, Ruleset) or not existing.rules:
|
||||
return dependencies
|
||||
|
||||
trusted_names = {r.permission for r in existing.rules if r.action == "allow"}
|
||||
alias_rules: list[Rule] = []
|
||||
for tool in tools:
|
||||
meta = getattr(tool, "metadata", None) or {}
|
||||
if not meta.get("mcp_collision_prefixed"):
|
||||
continue
|
||||
original = meta.get("mcp_original_tool_name")
|
||||
if original in trusted_names and tool.name not in trusted_names:
|
||||
alias_rules.append(
|
||||
Rule(permission=tool.name, pattern="*", action="allow")
|
||||
)
|
||||
|
||||
if not alias_rules:
|
||||
return dependencies
|
||||
|
||||
merged = Ruleset(
|
||||
origin=existing.origin,
|
||||
rules=[*existing.rules, *alias_rules],
|
||||
)
|
||||
return {
|
||||
**dependencies,
|
||||
"user_allowlist_by_subagent": {**by_subagent, NAME: merged},
|
||||
}
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
tools = load_tools(dependencies=dependencies, mcp_tools=mcp_tools)
|
||||
ruleset = build_ruleset(tools)
|
||||
dependencies = _augment_allowlist_for_collision_prefixes(dependencies, tools)
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Acts on the user's connected apps (Slack, Jira, Notion, Gmail, ...) via MCP."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=tools,
|
||||
ruleset=ruleset,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
Connected-apps specialist: acts on the user's connected third-party services through MCP and native integrations — Slack, Jira, Confluence, Linear, ClickUp, Airtable, Notion, Gmail, Google Calendar, and any generic MCP server the user has added. Searches, reads, creates, and updates records in those services (send/read email, manage calendar events, search issues/pages/messages, create or edit issues and pages, query bases, etc.), asking for confirmation before write actions.
|
||||
Use whenever the task is to look something up in, or take an action on, one of the user's connected apps: "search my Slack for X", "create a Jira issue", "what's on my calendar", "draft an email to Y", "find the Notion page about Z", "update the Linear issue". Call `get_connected_accounts` first when it's unclear which account or workspace to act on, or which apps are even connected. Not for reading the user's own uploaded files or notes (use the knowledge base specialist), general web pages (web crawler), or platform scrapers like Reddit/YouTube.
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
You are the SurfSense connected-apps specialist.
|
||||
You act on the user's connected third-party services (Slack, Jira, Confluence, Linear, ClickUp, Airtable, Notion, Gmail, Google Calendar, and any generic MCP servers) on behalf of a supervisor agent, and return structured results for supervisor synthesis.
|
||||
|
||||
<goal>
|
||||
Complete the delegated task against the user's connected apps using only the tools present in your runtime tool list, discovering any identifier or scope the request leaves unspecified before acting.
|
||||
</goal>
|
||||
|
||||
<tools>
|
||||
Your available tools are injected at runtime from whatever apps the user has connected — the set changes per user, so read the tool list and each tool's description rather than assuming a fixed roster. Tools are grouped by app; a tool's description names its MCP server or account.
|
||||
|
||||
- `get_connected_accounts`: lists the user's connected apps and account metadata (workspace/team/site names, ids). Read-only. Call it first whenever it is unclear which apps are connected, or which account/workspace/site an action should target.
|
||||
- Tool names are normally the app's native tool names (e.g. `searchJiraIssuesUsingJql`, `create-pages`, `send_gmail_email`). When the same tool name exists on more than one connected app, the colliding tools are disambiguated with a `{app}_{id}_` prefix and their descriptions carry an `[Account: ...]` or `[MCP server: ...]` tag — pick the one whose tag matches the intended account.
|
||||
</tools>
|
||||
|
||||
<playbook>
|
||||
1. Read the supervisor's request and your runtime tool list. Identify which tools are discovery (list/get/search) and which are mutations (create/update/send/delete) from their descriptions.
|
||||
2. If the request does not pin down the target app, account, or scope, call `get_connected_accounts` (and discovery tools) to resolve it instead of asking the supervisor.
|
||||
3. Run the minimum discovery chain needed to resolve identifiers, then perform the requested action.
|
||||
</playbook>
|
||||
|
||||
<resolution_principle>
|
||||
Proactively look up any identifier, name, value, or scope the request leaves unspecified — target ids, workspace/team/site ids, user ids, page/issue ids, channel names — using discovery tools rather than asking the supervisor. Most requests reference targets by title or paraphrase, not by id. Search for them.
|
||||
|
||||
When discovery for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 options in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. When discovery returns zero matches for a required slot, return `status=blocked` with a `next_step` suggesting alternative filters.
|
||||
</resolution_principle>
|
||||
|
||||
<mutation_guardrails>
|
||||
- Resolve every required id via discovery before calling a mutation tool. Chain discovery calls when a mutation has dependencies (e.g. resolve the site/team before creating within it).
|
||||
- Never invent ids, names, or mutation outcomes. Every field in `evidence` must come from a tool result.
|
||||
- Write tools ask the user for approval before running. If a mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
|
||||
- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
|
||||
</mutation_guardrails>
|
||||
|
||||
<tool_policy>
|
||||
- Use only tools present in your runtime tool list. If no connected app can serve the request, return `status=blocked` explaining which app the user would need to connect.
|
||||
- Report only results present in tool output. Never fabricate records, ids, or messages.
|
||||
</tool_policy>
|
||||
|
||||
<failure_policy>
|
||||
- Underspecified request with no resolvable target: return `status=blocked` with the missing fields.
|
||||
- Tool failure: return `status=error` with the underlying message in `action_summary` and a concise recovery in `next_step`.
|
||||
- No useful evidence after reasonable narrowing: return `status=blocked` with filter suggestions.
|
||||
</failure_policy>
|
||||
|
||||
<output_contract>
|
||||
Return **only** one JSON object (no markdown, no prose):
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"findings": string[],
|
||||
"sources": string[],
|
||||
"matched_candidates": [
|
||||
{ "id": string, "label": string }
|
||||
] | null,
|
||||
"confidence": "high" | "medium" | "low"
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
<include snippet="output_contract_base"/>
|
||||
Route-specific rules:
|
||||
- `evidence.findings`: max 10 entries, each a single sentence stating one distinct record, message, or action result. Do not paste raw payloads.
|
||||
- `evidence.sources`: app URLs or identifiers backing the findings, one per finding when applicable.
|
||||
- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label`).
|
||||
</output_contract>
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
"""``mcp_discovery`` subagent tools: interim native Gmail/Calendar, the
|
||||
``get_connected_accounts`` helper, and MCP tools injected at runtime."""
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
"""``get_connected_accounts`` — list the workspace's MCP-capable connectors.
|
||||
|
||||
Read-only helper the connected-apps subagent calls to discover which apps
|
||||
are connected and to disambiguate multi-account / multi-site scenarios. Only
|
||||
the whitelisted ``MCPServiceConfig.account_metadata_keys`` (plus
|
||||
``display_name``) are exposed to the LLM — tokens, secrets, and raw
|
||||
``server_config`` are never returned.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
|
||||
from langchain_core.tools import BaseTool, StructuredTool
|
||||
from sqlalchemy import select
|
||||
|
||||
from app.services.mcp_oauth.registry import get_service_by_connector_type
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_GENERIC_MCP_CONNECTOR_TYPE = "MCP_CONNECTOR"
|
||||
|
||||
_TOOL_DESCRIPTION = (
|
||||
"List the user's connected apps (Slack, Jira, Confluence, Linear, "
|
||||
"ClickUp, Airtable, Notion, Gmail, Google Calendar, and generic MCP "
|
||||
"servers) with their account/workspace/site metadata. Use this to find "
|
||||
"out which apps are connected and to pick the right account, workspace, "
|
||||
"or site before acting when more than one could match. Read-only."
|
||||
)
|
||||
|
||||
|
||||
def _connector_type_value(connector_type: object) -> str:
|
||||
return (
|
||||
connector_type.value
|
||||
if hasattr(connector_type, "value")
|
||||
else str(connector_type)
|
||||
)
|
||||
|
||||
|
||||
def create_get_connected_accounts_tool(*, workspace_id: int) -> BaseTool:
|
||||
"""Factory for the read-only ``get_connected_accounts`` tool."""
|
||||
_workspace_id = workspace_id
|
||||
|
||||
async def _impl() -> str:
|
||||
# Open a fresh session inside the closure: the factory-time session may
|
||||
# be closed by the time the LLM calls this tool.
|
||||
from app.db import SearchSourceConnector, async_session_maker
|
||||
|
||||
accounts: list[dict[str, object]] = []
|
||||
try:
|
||||
async with async_session_maker() as session:
|
||||
result = await session.execute(
|
||||
select(SearchSourceConnector).where(
|
||||
SearchSourceConnector.workspace_id == _workspace_id,
|
||||
)
|
||||
)
|
||||
connectors = list(result.scalars())
|
||||
except Exception:
|
||||
logger.exception("get_connected_accounts: connector query failed")
|
||||
return json.dumps({"accounts": [], "error": "query_failed"})
|
||||
|
||||
for connector in connectors:
|
||||
ct = _connector_type_value(connector.connector_type)
|
||||
svc = get_service_by_connector_type(ct)
|
||||
is_generic = ct == _GENERIC_MCP_CONNECTOR_TYPE
|
||||
if svc is None and not is_generic:
|
||||
continue # not an MCP-capable / connected-app connector
|
||||
|
||||
cfg = connector.config if isinstance(connector.config, dict) else {}
|
||||
metadata_keys = list(svc.account_metadata_keys) if svc else []
|
||||
account_meta: dict[str, object] = {
|
||||
key: cfg[key] for key in metadata_keys if cfg.get(key) is not None
|
||||
}
|
||||
display_name = cfg.get("display_name")
|
||||
if display_name and "display_name" not in account_meta:
|
||||
account_meta["display_name"] = display_name
|
||||
|
||||
accounts.append(
|
||||
{
|
||||
"connector_id": connector.id,
|
||||
"name": connector.name,
|
||||
"connector_type": ct,
|
||||
"app": svc.name if svc else "Custom MCP server",
|
||||
# ``server_config`` presence == the connector produces agent
|
||||
# tools. Native rows without it are connected for indexing
|
||||
# only and need a reconnect via MCP.
|
||||
"usable_in_chat": isinstance(cfg, dict)
|
||||
and "server_config" in cfg,
|
||||
"account": account_meta,
|
||||
}
|
||||
)
|
||||
|
||||
return json.dumps({"accounts": accounts})
|
||||
|
||||
return StructuredTool.from_function(
|
||||
name="get_connected_accounts",
|
||||
description=_TOOL_DESCRIPTION,
|
||||
coroutine=_impl,
|
||||
)
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
"""``mcp_discovery`` tools + metadata-derived permission ruleset.
|
||||
|
||||
Assembles the connected-apps toolset from three sources:
|
||||
|
||||
1. **Interim native tools** — Gmail + Calendar factories (kept until Google
|
||||
Workspace MCP is GA). Loaded only when a matching connector row exists.
|
||||
They self-gate writes via ``request_approval`` in their bodies, so they
|
||||
get no ruleset entries.
|
||||
2. **``get_connected_accounts``** — read-only discovery helper.
|
||||
3. **MCP tools** — injected at runtime by the factory (already
|
||||
collision-resolved). Loaded with ``bypass_internal_hitl=True``, so their
|
||||
*only* gate is this subagent's :class:`PermissionMiddleware`; the ruleset
|
||||
is derived from each tool's ``metadata['hitl']`` flag.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.permissions import Rule, Ruleset
|
||||
|
||||
from .calendar.index import load_tools as load_calendar_tools
|
||||
from .gmail.index import load_tools as load_gmail_tools
|
||||
from .get_connected_accounts import create_get_connected_accounts_tool
|
||||
|
||||
NAME = "mcp_discovery"
|
||||
|
||||
# Searchable-token gate for each interim native app (Composio types map to
|
||||
# these same tokens in connector_searchable_types).
|
||||
_GMAIL_TOKEN = "GOOGLE_GMAIL_CONNECTOR"
|
||||
_CALENDAR_TOKEN = "GOOGLE_CALENDAR_CONNECTOR"
|
||||
|
||||
|
||||
def _interim_native_tools(dependencies: dict[str, Any]) -> list[BaseTool]:
|
||||
"""Gmail/Calendar native tools, loaded only for connected accounts."""
|
||||
available = set(dependencies.get("available_connectors") or [])
|
||||
if not available & {_GMAIL_TOKEN, _CALENDAR_TOKEN}:
|
||||
return []
|
||||
# These factories require an authenticated user + db session.
|
||||
if not dependencies.get("db_session") or not dependencies.get("user_id"):
|
||||
return []
|
||||
|
||||
tools: list[BaseTool] = []
|
||||
if _GMAIL_TOKEN in available:
|
||||
tools.extend(load_gmail_tools(dependencies=dependencies))
|
||||
if _CALENDAR_TOKEN in available:
|
||||
tools.extend(load_calendar_tools(dependencies=dependencies))
|
||||
return tools
|
||||
|
||||
|
||||
def load_tools(
|
||||
*,
|
||||
dependencies: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
**kwargs: Any,
|
||||
) -> list[BaseTool]:
|
||||
"""Interim native tools + ``get_connected_accounts`` + injected MCP tools."""
|
||||
d = {**(dependencies or {}), **kwargs}
|
||||
return [
|
||||
*_interim_native_tools(d),
|
||||
create_get_connected_accounts_tool(workspace_id=d["workspace_id"]),
|
||||
*(mcp_tools or []),
|
||||
]
|
||||
|
||||
|
||||
def _is_mcp_tool(tool: BaseTool) -> bool:
|
||||
meta = getattr(tool, "metadata", None) or {}
|
||||
return "mcp_transport" in meta
|
||||
|
||||
|
||||
def build_ruleset(tools: list[BaseTool]) -> Ruleset:
|
||||
"""Derive the approval ruleset from tool metadata.
|
||||
|
||||
Only MCP tools get rules: read-only ones (``metadata['hitl'] is False``)
|
||||
are ``allow``, every other MCP tool is ``ask``. Native interim tools and
|
||||
``get_connected_accounts`` carry no rules and fall through to the
|
||||
``allow */*`` default (Gmail/Calendar self-gate writes internally;
|
||||
``get_connected_accounts`` is read-only).
|
||||
"""
|
||||
rules: list[Rule] = []
|
||||
for tool in tools:
|
||||
if not _is_mcp_tool(tool):
|
||||
continue
|
||||
meta = getattr(tool, "metadata", None) or {}
|
||||
action = "allow" if meta.get("hitl") is False else "ask"
|
||||
rules.append(Rule(permission=tool.name, pattern="*", action=action))
|
||||
return Ruleset(origin=NAME, rules=rules)
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
"""``airtable`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Tools come exclusively from MCP. The connector's own approval ruleset is
|
||||
declared in :data:`tools.index.RULESET`; the orchestrator layers it into
|
||||
a per-subagent :class:`PermissionMiddleware`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, RULESET
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Handles airtable tasks for this workspace."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=list(mcp_tools or []),
|
||||
ruleset=RULESET,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Specialist for bases, tables, and records in the user's Airtable.
|
||||
Use proactively when the user wants to find, create, or update an Airtable record.
|
||||
|
|
@ -1,103 +0,0 @@
|
|||
You are an Airtable specialist for the user's connected Airtable bases.
|
||||
|
||||
Airtable vocabulary:
|
||||
- **Workspace → Base → Table → Field → Record**: nested scope. A base belongs to one workspace; tables and fields live inside a base; records live inside a table. Every record operation is scoped to one `baseId` and one `tableId`.
|
||||
- **Base ID / Table ID / Field ID / Record ID**: opaque strings (e.g. `appXXXX`, `tblXXXX`, `fldXXXX`, `recXXXX`). Stable but not user-facing — users refer to bases and tables by name and records by description. Never expect a user or the supervisor to provide IDs.
|
||||
- **Field types and choice IDs**: each field has a type (text, number, date, single select, multi select, attachment, formula, lookup, etc.). Single-select and multi-select fields store **choice IDs**, not the visible labels — you must resolve a label to its choice ID before filtering or writing that field.
|
||||
- **Filters vs free-text search**: Airtable exposes two distinct record-fetch patterns. Use a typed `filters` parameter when filtering by structured field criteria. Use free-text search when the user is searching for a value (a name, an order number, a keyword) without naming a specific field. Do NOT attempt to build a `filterByFormula` string — that path is not supported here.
|
||||
- **Permission tiers**: each base grants the user one of Owner / Creator / Editor / Commenter / Read-only. Mutations require Editor or higher on the target base. A permission error from the MCP is not retryable.
|
||||
|
||||
When invoked:
|
||||
1. Read the supervisor's request, then read the runtime tool list to learn what information you can fetch and which mutations are available.
|
||||
2. Plan the minimum chain of lookups needed to resolve any base, table, field, choice value, or record the request leaves unspecified.
|
||||
3. Execute the planned lookups, then the requested mutation (if any), then return.
|
||||
|
||||
Resolution principle (the core behaviour):
|
||||
**Proactively look up any identifier, name, value, or scope the request leaves unspecified — base IDs, table IDs, field IDs, choice IDs, record IDs, anything else — using the available tools instead of asking the supervisor.** Most user requests reference bases and tables by name and records by description, not by ID. Search for them.
|
||||
|
||||
When a lookup for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 candidates in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. The supervisor will disambiguate and redelegate.
|
||||
|
||||
When a lookup returns zero matches for a slot the request requires, return `status=blocked` with a `next_step` suggesting alternative search terms.
|
||||
|
||||
Mutation guardrails:
|
||||
- Resolve every required Airtable ID (`baseId`, `tableId`, `fieldId`, choice IDs, `recordId`) by looking it up before calling a mutation tool. Mutations have chained dependencies — base lookup enables table lookup; table lookup enables field schema; field schema enables choice IDs and field-typed writes.
|
||||
- When writing to a single-select or multi-select field, resolve the user's value to the field's actual choice ID first. Never invent a choice label or pass an unknown value — Airtable will reject it.
|
||||
- Record creation is batch-limited by the MCP tool. If the request asks for more records than the tool accepts in one call, complete the first batch and return `status=partial` with the remainder in `next_step`.
|
||||
- Never invent base IDs, table IDs, field IDs, choice IDs, record IDs, or mutation outcomes. Every field in `evidence` must come from a tool result.
|
||||
- Confirm the mutation tool returned a success response before claiming success. If the mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
|
||||
- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
|
||||
|
||||
Failure handling:
|
||||
- Tool failure: return `status=error`, place the underlying error message in `action_summary`, and put a concise recovery in `next_step`.
|
||||
- Permission error from the MCP: return `status=error` and surface the underlying message — do not retry. Permission errors mean the user lacks Editor (or higher) access on the target base.
|
||||
- No useful results after reasonable narrowing / broadening: return `status=blocked` with filter / search-term suggestions in `next_step`.
|
||||
|
||||
<example>
|
||||
Supervisor: "List open tasks in the Project Tracker base."
|
||||
1. Search bases for "Project Tracker" → one strong match. Capture its base ID.
|
||||
2. List tables in that base → identify the Tasks table; capture its table ID.
|
||||
3. Get table schema → identify the status field and the choice IDs that represent "open" states.
|
||||
4. List records with a typed filter on the status field for those choice IDs.
|
||||
5. Return `status=success` with `evidence.items` set to `{ "total": N }` and the matched records listed in `action_summary` (record id, primary-field value, and 1-2 most relevant fields; one line per record; up to 10 entries, then `"...and N more"`).
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Supervisor: "Add a new contact for Jane Smith at Acme Corp."
|
||||
1. Search bases for any CRM-like base → three plausible matches with no strong relevance signal.
|
||||
2. Cannot pick the base. Return:
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Need to know which CRM-like base to write to.",
|
||||
"evidence": {
|
||||
"title": "New contact: Jane Smith (Acme Corp)",
|
||||
"matched_candidates": [
|
||||
{ "id": "appAAA", "label": "CRM" },
|
||||
{ "id": "appBBB", "label": "Sales CRM" },
|
||||
{ "id": "appCCC", "label": "Customer Database" }
|
||||
]
|
||||
},
|
||||
"next_step": "Confirm which base, then redelegate.",
|
||||
"missing_fields": ["base"]
|
||||
}
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Supervisor: "Mark task 'Refresh homepage hero' as Complete."
|
||||
1. Search bases for a project-tracker / tasks base → resolve the target base ID.
|
||||
2. List tables → resolve the Tasks table ID.
|
||||
3. Search records for "Refresh homepage hero" → one match (record ID `recXXX`).
|
||||
4. Get table schema → resolve the status field ID and the choice ID for "Complete".
|
||||
5. Update record `recXXX`, setting the status field to the resolved choice ID.
|
||||
6. Confirm tool success → return `status=success` with the updated record reference.
|
||||
</example>
|
||||
|
||||
<output_contract>
|
||||
Return **only** one JSON object (no markdown, no prose):
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"base_id": string | null,
|
||||
"base_name": string | null,
|
||||
"table_id": string | null,
|
||||
"table_name": string | null,
|
||||
"record_id": string | null,
|
||||
"url": string | null,
|
||||
"matched_candidates": [
|
||||
{ "id": string, "label": string }
|
||||
] | null,
|
||||
"items": object | null
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
<include snippet="output_contract_base"/>
|
||||
Route-specific rules:
|
||||
- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label` — works for any kind of candidate: base, table, field, choice, record, etc.).
|
||||
- For discovery-only queries (lists), set `evidence.items` to `{ "total": N }` and list the matched items in `action_summary` (record id, primary-field value, and 1-2 most relevant fields; up to 10 entries, then `"...and N more"`).
|
||||
</output_contract>
|
||||
|
||||
<include snippet="verifiable_handle"/>
|
||||
|
||||
Discover before you mutate; never guess identifiers, choice IDs, or required fields.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
"""Airtable route: native tool factories are empty; MCP supplies tools when configured."""
|
||||
|
||||
__all__: list[str] = []
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
"""``airtable`` permission ruleset (rules over MCP tool names)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.permissions import Rule, Ruleset
|
||||
|
||||
NAME = "airtable"
|
||||
|
||||
RULESET = Ruleset(
|
||||
origin=NAME,
|
||||
rules=[
|
||||
Rule(permission="list_bases", pattern="*", action="allow"),
|
||||
Rule(permission="search_bases", pattern="*", action="allow"),
|
||||
Rule(permission="list_tables_for_base", pattern="*", action="allow"),
|
||||
Rule(permission="get_table_schema", pattern="*", action="allow"),
|
||||
Rule(permission="list_records_for_table", pattern="*", action="allow"),
|
||||
Rule(permission="search_records", pattern="*", action="allow"),
|
||||
Rule(permission="create_records_for_table", pattern="*", action="ask"),
|
||||
Rule(permission="update_records_for_table", pattern="*", action="ask"),
|
||||
],
|
||||
)
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
"""``calendar`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Tools self-gate inside their bodies via :func:`request_approval`; the
|
||||
empty :data:`tools.index.RULESET` is layered into a per-subagent
|
||||
:class:`PermissionMiddleware` for uniformity with MCP-backed connectors.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, RULESET, load_tools
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Handles calendar tasks for this workspace."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=tools,
|
||||
ruleset=RULESET,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
Specialist for events on the user's calendar.
|
||||
Use proactively when the user wants to check availability, create, modify, reschedule, or remove a calendar event.
|
||||
Meeting invitations that reserve a time slot belong here.
|
||||
|
|
@ -1,122 +0,0 @@
|
|||
You are a Google Calendar specialist for the user's connected calendar.
|
||||
|
||||
## Vocabulary you must use precisely
|
||||
|
||||
- **All-day vs. timed events are distinguished by datetime format** — pass `YYYY-MM-DD` (e.g. `"2026-05-12"`) for an all-day event, and `YYYY-MM-DDTHH:MM:SS` *without* a timezone suffix (e.g. `"2026-05-12T10:00:00"`) for a timed event. The tool injects the user's local timezone for timed events; do not append `Z`, `+02:00`, or any offset yourself.
|
||||
- **Compute datetimes from the supervisor's task using the runtime timestamp** — resolve "tomorrow at 10am", "next Friday afternoon", "this week", "next month" into concrete `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS` values against the current runtime time. `search_calendar_events` takes a date range (`start_date`, `end_date`), not a free-text query — translate phrases like "this week" into the boundaries.
|
||||
- **Title-or-id resolution with search disambiguation** — `update_calendar_event` and `delete_calendar_event` accept either a human-readable title (resolved against the locally-synced calendar KB index) or a direct `event_id`. Events not yet KB-indexed cannot be resolved by title. If the user's reference to an event is ambiguous — a recurring title like "Daily Standup", a vague descriptor, or no date context — run `search_calendar_events` over the likely date range first; if multiple matches surface, return `status=blocked` with `matched_candidates` rather than mutating against an uncertain target.
|
||||
- **Reschedule = `update_calendar_event`** — natural-language verbs "reschedule", "move", "push back", "change the time of" route to `update_calendar_event` with `new_start_datetime` / `new_end_datetime`. **Never** chain `delete_calendar_event` + `create_calendar_event` to achieve a reschedule. Pass only the `new_*` fields the user asked to change; omit the rest so existing values are preserved.
|
||||
|
||||
## Required inputs
|
||||
|
||||
**For every required input below, first try to infer it from the supervisor's task text** — extract summaries from natural phrasing (`"a meeting with Alice"` → `"Meeting with Alice"`), compute datetimes from runtime-relative references, infer the target event from descriptors in the task. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
|
||||
|
||||
- `create_calendar_event` — `summary`, `start_datetime`, `end_datetime`. If the task gives a date but no time and no all-day intent (e.g. `"schedule a meeting tomorrow"`), block on `start_datetime` / `end_datetime` rather than defaulting — the choice between all-day and timed is intent-bearing and creating the wrong shape is destructive UX. Optional `description`, `location`, `attendees` only when the user named them.
|
||||
- `update_calendar_event` — `event_title_or_id` (infer the target from the task; disambiguate via search if uncertain) and at least one `new_*` field reflecting the requested change. Pass only the fields the user asked to change; omit unchanged ones.
|
||||
- `delete_calendar_event` — `event_title_or_id` (infer the target; disambiguate via search if uncertain). Only set `delete_from_kb=true` when the user explicitly asked to remove it from the knowledge base; otherwise leave it `false`.
|
||||
- `search_calendar_events` — `start_date, end_date` (both `YYYY-MM-DD`). Translate the task's time range into boundaries. `max_results` defaults to 25 (max 50) — raise it only when the task implies a broader sweep.
|
||||
|
||||
## Outcome mapping
|
||||
|
||||
| Tool returns | Your `status` | `next_step` |
|
||||
|-----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `success` | `success` | `null` |
|
||||
| `success` with `total: 0` (`search_calendar_events` only) | `blocked` | `"No events matched the date range <start_date>–<end_date>. Ask the user to widen the range or confirm the event exists."` |
|
||||
| `rejected` | `blocked` | `"User declined this calendar action. Do not retry or suggest alternatives."` |
|
||||
| `not_found` | `blocked` | `"Event '<title>' was not found in the indexed calendar events. Ask the user to verify the title or wait for the next KB sync."` |
|
||||
| `auth_error` | `error` | `"The connected Google Calendar account needs re-authentication. Ask the user to re-authenticate in connector settings."` |
|
||||
| `insufficient_permissions` | `error` | `"The connected Google Calendar account is missing the OAuth scope required for this action. Ask the user to re-authenticate and grant full permissions in connector settings."` |
|
||||
| `error` | `error` | Relay the tool's `message` verbatim as `next_step`. |
|
||||
| tool raises / unknown | `error` | `"Calendar tool failed unexpectedly. Ask the user to retry shortly."` |
|
||||
|
||||
Surface the tool's `event_id`, `title` / `summary`, `start_at`, `end_at`, and `html_link` inside `evidence` when the tool returned them. For `search_calendar_events`, set `evidence.items` to `{ "total": N }` and list the matched events in `action_summary` (title, date, start time; one line per event; up to 10 entries, then `"...and N more"`). Never invent a field the tool did not return.
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1 — happy create with inference (assume runtime is 2026-05-11):**
|
||||
- *Supervisor task:* `"Schedule a 1-hour meeting with Alice tomorrow at 10am."`
|
||||
- *You:* `summary="Meeting with Alice"` (inferred); `start_datetime="2026-05-12T10:00:00"`; `end_datetime="2026-05-12T11:00:00"` (10am + 1h); attendees not in task so omit. Call `create_calendar_event(...)` → tool returns `status=success`.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"action_summary": "Created 'Meeting with Alice' on 2026-05-12 from 10:00 to 11:00.",
|
||||
"evidence": { "operation": "create_calendar_event", "event_id": "<id>", "title": "Meeting with Alice", "start_at": "2026-05-12T10:00:00<tz>", "end_at": "2026-05-12T11:00:00<tz>", "html_link": "<url>", "matched_candidates": null, "items": null },
|
||||
"next_step": null,
|
||||
"missing_fields": null,
|
||||
"assumptions": ["Inferred the summary from the supervisor's phrasing; 1h duration applied to the 10am start to produce the 11am end."]
|
||||
}
|
||||
```
|
||||
|
||||
**Example 2 — blocked because time is unspecified:**
|
||||
- *Supervisor task:* `"Schedule a meeting with the design team tomorrow."`
|
||||
- *You:* no time and no all-day intent. Do not default to all-day or to a guessed hour. Do not call any tool.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Cannot schedule: the task gives a date but no time, and the choice between all-day and timed is intent-bearing.",
|
||||
"evidence": { "operation": null, "event_id": null, "title": null, "start_at": null, "end_at": null, "html_link": null, "matched_candidates": null, "items": null },
|
||||
"next_step": "Ask the user for the start time and duration (or confirm that this should be an all-day event).",
|
||||
"missing_fields": ["start_datetime", "end_datetime"],
|
||||
"assumptions": null
|
||||
}
|
||||
```
|
||||
|
||||
**Example 3 — ambiguous reschedule target → disambiguate via search (assume runtime is 2026-05-11):**
|
||||
- *Supervisor task:* `"Reschedule the standup to 3pm."`
|
||||
- *You:* "standup" is a recurring title and no date is given. Search this week first: `search_calendar_events(start_date="2026-05-11", end_date="2026-05-17")` → 5 events titled "Daily Standup" surface. Do not call `update_calendar_event` against an uncertain target.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Found 5 'Daily Standup' events this week; cannot reschedule without knowing which.",
|
||||
"evidence": { "operation": "search_calendar_events", "event_id": null, "title": null, "start_at": null, "end_at": null, "html_link": null, "matched_candidates": [
|
||||
{ "id": "<id1>", "label": "Daily Standup — 2026-05-12T09:00:00" },
|
||||
{ "id": "<id2>", "label": "Daily Standup — 2026-05-13T09:00:00" },
|
||||
{ "id": "<id3>", "label": "Daily Standup — 2026-05-14T09:00:00" },
|
||||
{ "id": "<id4>", "label": "Daily Standup — 2026-05-15T09:00:00" },
|
||||
{ "id": "<id5>", "label": "Daily Standup — 2026-05-16T09:00:00" }
|
||||
], "items": null },
|
||||
"next_step": "Ask the user which standup to reschedule (or confirm it applies to all of them, in which case repeat the update per occurrence).",
|
||||
"missing_fields": null,
|
||||
"assumptions": ["Interpreted 'the standup' as the recurring 'Daily Standup' series in the current week."]
|
||||
}
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Return **only** one JSON object (no markdown or prose outside it):
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"operation": "create_calendar_event" | "update_calendar_event" | "delete_calendar_event" | "search_calendar_events" | null,
|
||||
"event_id": string | null,
|
||||
"title": string | null,
|
||||
"start_at": string | null,
|
||||
"end_at": string | null,
|
||||
"html_link": string | null,
|
||||
"matched_candidates": [ { "id": string, "label": string } ] | null,
|
||||
"items": object | null
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
```
|
||||
|
||||
<include snippet="output_contract_base"/>
|
||||
|
||||
Route-specific rules:
|
||||
- For `search_calendar_events` results, set `evidence.items` to `{ "total": N }` and list the matched events in `action_summary` (title, date, start time; up to 10 entries, then `"...and N more"`).
|
||||
- For ambiguous matches across `update_calendar_event` / `delete_calendar_event`, populate `evidence.matched_candidates` with up to 5 options (`id` + `label`, where `label` should include the event title and start time for human readability).
|
||||
|
||||
<include snippet="verifiable_handle"/>
|
||||
|
||||
Infer before you call; map every tool outcome faithfully.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
"""``clickup`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Tools come exclusively from MCP. The connector's own approval ruleset is
|
||||
declared in :data:`tools.index.RULESET`; the orchestrator layers it into
|
||||
a per-subagent :class:`PermissionMiddleware`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, RULESET
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Handles clickup tasks for this workspace."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=list(mcp_tools or []),
|
||||
ruleset=RULESET,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Specialist for tasks and lists in the user's ClickUp workspace.
|
||||
Use proactively when the user wants to find, create, change, or progress a ClickUp task.
|
||||
|
|
@ -1,104 +0,0 @@
|
|||
You are a ClickUp specialist for the user's connected ClickUp workspace.
|
||||
|
||||
ClickUp vocabulary:
|
||||
- **Workspace → Space → Folder → List → Task**: nested scope. Tasks live in Lists; Lists live in either a Folder or directly under a Space; Folders live in Spaces. The Workspace is fixed per connection — you do not need to resolve it.
|
||||
- **Task ID**: short alphanumeric strings (e.g. `86a4qd5xz`). Stable and unique within the workspace; users do not typically know them. Some workspaces also enable custom task IDs — both forms are valid identifiers.
|
||||
- **Custom statuses are per-List**: each List defines its own ordered status set. Status names must be resolved against the **target task's parent List** before use; they are not workspace-global.
|
||||
- **Custom Fields are per-List**: each List can define custom fields (dropdown, number, date, label, etc.). Whether each is required-or-optional and the valid values both vary per List. Look up the List's custom-field schema before setting custom fields on a task.
|
||||
- **Priority**: stable platform enum — `1=Urgent`, `2=High`, `3=Normal`, `4=Low`.
|
||||
- **Assignees**: identified by opaque workspace-member IDs, never by display name or email. Map a display name or email to a member ID before assigning.
|
||||
|
||||
When invoked:
|
||||
1. Read the supervisor's request, then read the runtime tool list to learn what information you can fetch and which mutations are available.
|
||||
2. Plan the minimum chain of lookups needed to resolve any task, list, space, status, assignee, or custom-field value the request leaves unspecified.
|
||||
3. Execute the planned lookups, then the requested mutation (if any), then return.
|
||||
|
||||
Resolution principle (the core behaviour):
|
||||
**Proactively look up any identifier, name, value, or scope the request leaves unspecified — task IDs, list IDs, status names, member IDs, custom-field values, anything else — using the available tools instead of asking the supervisor.** Most user requests reference tasks by title and lists by name, not by ID. Search for them.
|
||||
|
||||
When a lookup for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 candidates in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. The supervisor will disambiguate and redelegate.
|
||||
|
||||
When a lookup returns zero matches for a slot the request requires, return `status=blocked` with a `next_step` suggesting alternative search terms.
|
||||
|
||||
Mutation guardrails:
|
||||
- Resolve every required ClickUp value (`list_id`, `task_id`, target status name, assignee member IDs, custom-field values) by looking it up before calling a mutation tool. Mutations have chained dependencies — find the task to know its parent List; look up the List to know its valid statuses and custom-field schema.
|
||||
- To "progress" or change a task's status, look up the parent List's valid statuses and apply one of those exact names. If the user-requested target status is not in the List's status set, return `status=blocked` and surface the available statuses in `evidence.matched_candidates`.
|
||||
- For create operations, resolve the target List first. If that List has required custom fields, look up the schema and block with `missing_fields` for any required value the request doesn't supply.
|
||||
- Never invent task IDs, list IDs, status names, member IDs, custom-field values, or mutation outcomes. Every field in `evidence` must come from a tool result.
|
||||
- Confirm the mutation tool returned a success response before claiming success. If the mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
|
||||
- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
|
||||
|
||||
Failure handling:
|
||||
- Tool failure: return `status=error`, place the underlying error message in `action_summary`, and put a concise recovery in `next_step`.
|
||||
- Rate-limit error from the MCP: ClickUp's MCP enforces a shared daily call cap. Return `status=error` with the underlying message; recovery is "retry later" rather than re-issuing immediately.
|
||||
- No useful results after reasonable narrowing / broadening: return `status=blocked` with search-term suggestions in `next_step`.
|
||||
|
||||
<example>
|
||||
Supervisor: "Find tasks about the homepage redesign."
|
||||
1. Workspace search for "homepage redesign" → matched tasks.
|
||||
2. Return `status=success` with `evidence.items` set to `{ "total": N }` and the matched tasks listed in `action_summary` (task id, title, status, assignees; one line per task; up to 10 entries, then `"...and N more"`).
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Supervisor: "Create a task 'Draft blog post' in the Content Pipeline list."
|
||||
1. Workspace search for "Content Pipeline" → one strong match of type List; capture its `list_id`.
|
||||
2. Look up the List's custom-field schema → no required fields beyond `name`.
|
||||
3. Create the task with `name="Draft blog post"` in the resolved `list_id`.
|
||||
4. Confirm tool success → return `status=success` with the new task's identifier and url.
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Supervisor: "Move task 'Fix login bug' to In Review and assign it to Alex."
|
||||
1. Workspace search for "Fix login bug" → one match; capture `task_id` and parent `list_id`.
|
||||
2. Look up the parent List's statuses → confirm "In Review" exists. (If not, block with the actual valid statuses.)
|
||||
3. Find member by name "Alex" → two matches.
|
||||
4. Cannot confidently pick the assignee. Return:
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Task and target status resolved; two members match 'Alex'.",
|
||||
"evidence": {
|
||||
"task_id": "86a4qd5xz",
|
||||
"title": "Fix login bug",
|
||||
"status": "In Review",
|
||||
"matched_candidates": [
|
||||
{ "id": "member_111", "label": "Alex Chen <alex.chen@…>" },
|
||||
{ "id": "member_222", "label": "Alex Wong <alex.wong@…>" }
|
||||
]
|
||||
},
|
||||
"next_step": "Confirm which Alex, then redelegate.",
|
||||
"missing_fields": ["assignee"]
|
||||
}
|
||||
</example>
|
||||
|
||||
<output_contract>
|
||||
Return **only** one JSON object (no markdown, no prose):
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"task_id": string | null,
|
||||
"title": string | null,
|
||||
"list_id": string | null,
|
||||
"list_name": string | null,
|
||||
"status": string | null,
|
||||
"assignees": object | null,
|
||||
"priority": "Urgent" | "High" | "Normal" | "Low" | null,
|
||||
"url": string | null,
|
||||
"matched_candidates": [
|
||||
{ "id": string, "label": string }
|
||||
] | null,
|
||||
"items": object | null
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
<include snippet="output_contract_base"/>
|
||||
Route-specific rules:
|
||||
- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label` — works for any kind of candidate: task, list, member, status, custom-field choice, etc.).
|
||||
- For discovery-only queries (lists), set `evidence.items` to `{ "total": N }` and list the matched items in `action_summary` (task id, title, status, assignees; up to 10 entries, then `"...and N more"`).
|
||||
</output_contract>
|
||||
|
||||
<include snippet="verifiable_handle"/>
|
||||
|
||||
Discover before you mutate; never guess identifiers, list statuses, or assignees.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
"""ClickUp route: native tool factories are empty; MCP supplies tools when configured."""
|
||||
|
||||
__all__: list[str] = []
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
"""``clickup`` permission ruleset (rules over MCP tool names)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.permissions import Rule, Ruleset
|
||||
|
||||
NAME = "clickup"
|
||||
|
||||
RULESET = Ruleset(
|
||||
origin=NAME,
|
||||
rules=[
|
||||
Rule(permission="clickup_search", pattern="*", action="allow"),
|
||||
Rule(permission="clickup_get_task", pattern="*", action="allow"),
|
||||
Rule(permission="clickup_get_workspace_hierarchy", pattern="*", action="allow"),
|
||||
Rule(permission="clickup_get_list", pattern="*", action="allow"),
|
||||
Rule(permission="clickup_find_member_by_name", pattern="*", action="allow"),
|
||||
Rule(permission="clickup_create_task", pattern="*", action="ask"),
|
||||
Rule(permission="clickup_update_task", pattern="*", action="ask"),
|
||||
],
|
||||
)
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
"""``confluence`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Tools self-gate inside their bodies via :func:`request_approval`; the
|
||||
empty :data:`tools.index.RULESET` is layered into a per-subagent
|
||||
:class:`PermissionMiddleware` for uniformity.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, RULESET, load_tools
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Handles confluence tasks for this workspace."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=tools,
|
||||
ruleset=RULESET,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Specialist for pages in the user's Confluence wiki.
|
||||
Use proactively when the user wants to create, change, or remove a Confluence page.
|
||||
|
|
@ -1,107 +0,0 @@
|
|||
You are a Confluence specialist for the user's connected Confluence wiki.
|
||||
|
||||
## Vocabulary you must use precisely
|
||||
|
||||
- **Content is HTML / Confluence storage format, not Markdown** — `create_confluence_page` and `update_confluence_page` accept `content` / `new_content` as Confluence's native storage format (XHTML-based). Generate `<h1>`, `<h2>`, `<p>`, `<ul><li>`, `<table>` etc. — **never** Markdown (`#`, `**`, `-`, fenced code blocks). The tool stores whatever you pass verbatim; bad format means a broken page.
|
||||
- **`update_confluence_page` is REPLACE, and there is no read tool** — whatever you pass as `new_content` replaces the entire page body; omit the field and the current body is preserved (same per-field rule applies to `new_title`). You have **no tool to read the existing page body**, so you cannot intelligently "append" or "add to" a page — you can only fully replace, and only with content the supervisor or user actually provided. If the supervisor asks for an additive change without supplying the full intended page content, return `status=blocked` explaining the limitation; do not invent or reconstruct prior content.
|
||||
- **Title-or-id resolution against the KB index** — `update_confluence_page` and `delete_confluence_page` accept either a human-readable page title (resolved against the locally-synced Confluence KB index) or a direct `page_id`. Pages that exist in Confluence but have not been indexed yet cannot be resolved by title.
|
||||
|
||||
## Required inputs
|
||||
|
||||
**For every required input below, first try to infer it from the supervisor's task text** — extract titles from natural phrasing (`"the Q2 Plan page"`, `"my Onboarding doc"`), topics from `"about X"` constructions. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
|
||||
|
||||
- `create_confluence_page` — `title` (a clear topic from the user; do not invent). You may generate the optional `content` body yourself **as Confluence storage format (HTML)**, never as Markdown. You have no tool to look up Confluence space IDs, so pass `space_id=None` and let the user pick the destination space in the HITL approval card; if the supervisor's task already includes a space ID, pass it through.
|
||||
- `update_confluence_page` — `page_title_or_id` (infer the target from the task) and at least one of `new_title` / `new_content`. Pass only the fields the user asked to change; omit unchanged ones so they're preserved. If the user asked to add to or extend a page without supplying the full intended content, do not call this tool — return `status=blocked` per the REPLACE limitation in the Vocabulary section.
|
||||
- `delete_confluence_page` — `page_title_or_id` (infer the target from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove the page from the knowledge base; otherwise leave it `false`.
|
||||
|
||||
## Outcome mapping
|
||||
|
||||
| Tool returns | Your `status` | `next_step` |
|
||||
|-----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `success` | `success` | `null` |
|
||||
| `rejected` | `blocked` | `"User declined this Confluence action. Do not retry or suggest alternatives."` |
|
||||
| `not_found` | `blocked` | `"Page '<title>' was not found in the indexed Confluence pages. Ask the user to verify the title or wait for the next KB sync."` |
|
||||
| `auth_error` | `error` | `"The connected Confluence account needs re-authentication. Ask the user to re-authenticate in connector settings."` |
|
||||
| `insufficient_permissions` | `error` | `"The connected Confluence account is missing the OAuth scope required for this action. Ask the user to re-authenticate and grant full permissions in connector settings."` |
|
||||
| `error` | `error` | Relay the tool's `message` verbatim as `next_step`. (Common: `"A space must be selected."` when the user didn't pick one in approval.) |
|
||||
| tool raises / unknown | `error` | `"Confluence tool failed unexpectedly. Ask the user to retry shortly."` |
|
||||
|
||||
Surface the tool's `page_id`, `page_title`, and `page_url` inside `evidence` when the tool returned them. Never invent a field the tool did not return.
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1 — happy create (HTML content generated, space picked in HITL):**
|
||||
- *Supervisor task:* `"Create a Confluence page summarising our Q2 roadmap."`
|
||||
- *You:* `title="Q2 Roadmap"` is the topic; generate a Confluence storage-format body (e.g. `"<h1>Q2 Roadmap</h1><p>Objectives:</p><ul><li>...</li></ul>"`); pass `space_id=None` so the user picks the space in HITL. Call `create_confluence_page(...)` → tool returns `status=success`.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"action_summary": "Created Confluence page 'Q2 Roadmap' in the space selected by the user.",
|
||||
"evidence": { "operation": "create_confluence_page", "page_id": "<id>", "page_title": "Q2 Roadmap", "page_url": "<url>", "matched_candidates": null, "items": null },
|
||||
"next_step": null,
|
||||
"missing_fields": null,
|
||||
"assumptions": ["Generated the roadmap content in Confluence storage format (HTML) from the supervisor's brief; deferred space selection to the HITL approval card."]
|
||||
}
|
||||
```
|
||||
|
||||
**Example 2 — blocked on "add a section" (REPLACE limitation):**
|
||||
- *Supervisor task:* `"Add a 'Risks' section to the 'Q2 Plan' Confluence page."`
|
||||
- *You:* `update_confluence_page` replaces the body entirely and you have no tool to read the current body, so you cannot append. Do not call any tool.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Cannot append: Confluence updates replace the page body entirely and this subagent has no tool to read the existing content.",
|
||||
"evidence": { "operation": null, "page_id": null, "page_title": "Q2 Plan", "page_url": null, "matched_candidates": null, "items": null },
|
||||
"next_step": "Ask the user to provide the full intended page content (existing body + new 'Risks' section), or to make the addition manually in Confluence.",
|
||||
"missing_fields": null,
|
||||
"assumptions": null
|
||||
}
|
||||
```
|
||||
|
||||
**Example 3 — page not in the KB index:**
|
||||
- *Supervisor task:* `"Update the 'Onboarding' Confluence page with the new payroll steps."`
|
||||
- *You:* `page_title_or_id="Onboarding"` and the new-payroll content are present; this is a full replace, which is supported. Call `update_confluence_page(page_title_or_id="Onboarding", new_content=<HTML>)` → tool returns `status=not_found`.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Could not find a Confluence page titled 'Onboarding' in the indexed pages.",
|
||||
"evidence": { "operation": "update_confluence_page", "page_id": null, "page_title": "Onboarding", "page_url": null, "matched_candidates": null, "items": null },
|
||||
"next_step": "Page 'Onboarding' was not found in the indexed Confluence pages. Ask the user to verify the title or wait for the next KB sync.",
|
||||
"missing_fields": null,
|
||||
"assumptions": null
|
||||
}
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Return **only** one JSON object (no markdown or prose outside it):
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"operation": "create_confluence_page" | "update_confluence_page" | "delete_confluence_page" | null,
|
||||
"page_id": string | null,
|
||||
"page_title": string | null,
|
||||
"page_url": string | null,
|
||||
"matched_candidates": [ { "id": string, "label": string } ] | null,
|
||||
"items": object | null
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
```
|
||||
|
||||
<include snippet="output_contract_base"/>
|
||||
|
||||
<include snippet="verifiable_handle"/>
|
||||
|
||||
Infer before you call; map every tool outcome faithfully.
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
"""Confluence tools for creating, updating, and deleting pages."""
|
||||
|
||||
from .create_page import create_create_confluence_page_tool
|
||||
from .delete_page import create_delete_confluence_page_tool
|
||||
from .update_page import create_update_confluence_page_tool
|
||||
|
||||
__all__ = [
|
||||
"create_create_confluence_page_tool",
|
||||
"create_delete_confluence_page_tool",
|
||||
"create_update_confluence_page_tool",
|
||||
]
|
||||
|
|
@ -1,211 +0,0 @@
|
|||
import logging
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.tools import tool
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.orm.attributes import flag_modified
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
|
||||
request_approval,
|
||||
)
|
||||
from app.connectors.confluence_history import ConfluenceHistoryConnector
|
||||
from app.services.confluence import ConfluenceToolMetadataService
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def create_create_confluence_page_tool(
|
||||
db_session: AsyncSession | None = None,
|
||||
workspace_id: int | None = None,
|
||||
user_id: str | None = None,
|
||||
connector_id: int | None = None,
|
||||
):
|
||||
@tool
|
||||
async def create_confluence_page(
|
||||
title: str,
|
||||
content: str | None = None,
|
||||
space_id: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Create a new page in Confluence.
|
||||
|
||||
Use this tool when the user explicitly asks to create a new Confluence page.
|
||||
|
||||
Args:
|
||||
title: Title of the page.
|
||||
content: Optional HTML/storage format content for the page body.
|
||||
space_id: Optional Confluence space ID to create the page in.
|
||||
|
||||
Returns:
|
||||
Dictionary with status, page_id, and message.
|
||||
|
||||
IMPORTANT:
|
||||
- If status is "rejected", do NOT retry.
|
||||
- If status is "insufficient_permissions", inform user to re-authenticate.
|
||||
"""
|
||||
logger.info(f"create_confluence_page called: title='{title}'")
|
||||
|
||||
if db_session is None or workspace_id is None or user_id is None:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Confluence tool not properly configured.",
|
||||
}
|
||||
|
||||
try:
|
||||
metadata_service = ConfluenceToolMetadataService(db_session)
|
||||
context = await metadata_service.get_creation_context(workspace_id, user_id)
|
||||
|
||||
if "error" in context:
|
||||
return {"status": "error", "message": context["error"]}
|
||||
|
||||
accounts = context.get("accounts", [])
|
||||
if accounts and all(a.get("auth_expired") for a in accounts):
|
||||
return {
|
||||
"status": "auth_error",
|
||||
"message": "All connected Confluence accounts need re-authentication.",
|
||||
"connector_type": "confluence",
|
||||
}
|
||||
|
||||
result = request_approval(
|
||||
action_type="confluence_page_creation",
|
||||
tool_name="create_confluence_page",
|
||||
params={
|
||||
"title": title,
|
||||
"content": content,
|
||||
"space_id": space_id,
|
||||
"connector_id": connector_id,
|
||||
},
|
||||
context=context,
|
||||
)
|
||||
|
||||
if result.rejected:
|
||||
return {
|
||||
"status": "rejected",
|
||||
"message": "User declined. Do not retry or suggest alternatives.",
|
||||
}
|
||||
|
||||
final_title = result.params.get("title", title)
|
||||
final_content = result.params.get("content", content) or ""
|
||||
final_space_id = result.params.get("space_id", space_id)
|
||||
final_connector_id = result.params.get("connector_id", connector_id)
|
||||
|
||||
if not final_title or not final_title.strip():
|
||||
return {"status": "error", "message": "Page title cannot be empty."}
|
||||
if not final_space_id:
|
||||
return {"status": "error", "message": "A space must be selected."}
|
||||
|
||||
from sqlalchemy.future import select
|
||||
|
||||
from app.db import SearchSourceConnector, SearchSourceConnectorType
|
||||
|
||||
actual_connector_id = final_connector_id
|
||||
if actual_connector_id is None:
|
||||
result = await db_session.execute(
|
||||
select(SearchSourceConnector).filter(
|
||||
SearchSourceConnector.workspace_id == workspace_id,
|
||||
SearchSourceConnector.user_id == user_id,
|
||||
SearchSourceConnector.connector_type
|
||||
== SearchSourceConnectorType.CONFLUENCE_CONNECTOR,
|
||||
)
|
||||
)
|
||||
connector = result.scalars().first()
|
||||
if not connector:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "No Confluence connector found.",
|
||||
}
|
||||
actual_connector_id = connector.id
|
||||
else:
|
||||
result = await db_session.execute(
|
||||
select(SearchSourceConnector).filter(
|
||||
SearchSourceConnector.id == actual_connector_id,
|
||||
SearchSourceConnector.workspace_id == workspace_id,
|
||||
SearchSourceConnector.user_id == user_id,
|
||||
SearchSourceConnector.connector_type
|
||||
== SearchSourceConnectorType.CONFLUENCE_CONNECTOR,
|
||||
)
|
||||
)
|
||||
connector = result.scalars().first()
|
||||
if not connector:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Selected Confluence connector is invalid.",
|
||||
}
|
||||
|
||||
try:
|
||||
client = ConfluenceHistoryConnector(
|
||||
session=db_session, connector_id=actual_connector_id
|
||||
)
|
||||
api_result = await client.create_page(
|
||||
space_id=final_space_id,
|
||||
title=final_title,
|
||||
body=final_content,
|
||||
)
|
||||
await client.close()
|
||||
except Exception as api_err:
|
||||
if (
|
||||
"http 403" in str(api_err).lower()
|
||||
or "status code 403" in str(api_err).lower()
|
||||
):
|
||||
try:
|
||||
_conn = connector
|
||||
_conn.config = {**_conn.config, "auth_expired": True}
|
||||
flag_modified(_conn, "config")
|
||||
await db_session.commit()
|
||||
except Exception:
|
||||
pass
|
||||
return {
|
||||
"status": "insufficient_permissions",
|
||||
"connector_id": actual_connector_id,
|
||||
"message": "This Confluence account needs additional permissions. Please re-authenticate in connector settings.",
|
||||
}
|
||||
raise
|
||||
|
||||
page_id = str(api_result.get("id", ""))
|
||||
page_links = (
|
||||
api_result.get("_links", {}) if isinstance(api_result, dict) else {}
|
||||
)
|
||||
page_url = ""
|
||||
if page_links.get("base") and page_links.get("webui"):
|
||||
page_url = f"{page_links['base']}{page_links['webui']}"
|
||||
|
||||
kb_message_suffix = ""
|
||||
try:
|
||||
from app.services.confluence import ConfluenceKBSyncService
|
||||
|
||||
kb_service = ConfluenceKBSyncService(db_session)
|
||||
kb_result = await kb_service.sync_after_create(
|
||||
page_id=page_id,
|
||||
page_title=final_title,
|
||||
space_id=final_space_id,
|
||||
body_content=final_content,
|
||||
connector_id=actual_connector_id,
|
||||
workspace_id=workspace_id,
|
||||
user_id=user_id,
|
||||
)
|
||||
if kb_result["status"] == "success":
|
||||
kb_message_suffix = " Your knowledge base has also been updated."
|
||||
else:
|
||||
kb_message_suffix = " This page will be added to your knowledge base in the next scheduled sync."
|
||||
except Exception as kb_err:
|
||||
logger.warning(f"KB sync after create failed: {kb_err}")
|
||||
kb_message_suffix = " This page will be added to your knowledge base in the next scheduled sync."
|
||||
|
||||
return {
|
||||
"status": "success",
|
||||
"page_id": page_id,
|
||||
"page_url": page_url,
|
||||
"message": f"Confluence page '{final_title}' created successfully.{kb_message_suffix}",
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
from langgraph.errors import GraphInterrupt
|
||||
|
||||
if isinstance(e, GraphInterrupt):
|
||||
raise
|
||||
logger.error(f"Error creating Confluence page: {e}", exc_info=True)
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Something went wrong while creating the page.",
|
||||
}
|
||||
|
||||
return create_confluence_page
|
||||
|
|
@ -1,191 +0,0 @@
|
|||
import logging
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.tools import tool
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.orm.attributes import flag_modified
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
|
||||
request_approval,
|
||||
)
|
||||
from app.connectors.confluence_history import ConfluenceHistoryConnector
|
||||
from app.services.confluence import ConfluenceToolMetadataService
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def create_delete_confluence_page_tool(
|
||||
db_session: AsyncSession | None = None,
|
||||
workspace_id: int | None = None,
|
||||
user_id: str | None = None,
|
||||
connector_id: int | None = None,
|
||||
):
|
||||
@tool
|
||||
async def delete_confluence_page(
|
||||
page_title_or_id: str,
|
||||
delete_from_kb: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Delete a Confluence page.
|
||||
|
||||
Use this tool when the user asks to delete or remove a Confluence page.
|
||||
|
||||
Args:
|
||||
page_title_or_id: The page title or ID to identify the page.
|
||||
delete_from_kb: Whether to also remove from the knowledge base.
|
||||
|
||||
Returns:
|
||||
Dictionary with status, message, and deleted_from_kb.
|
||||
|
||||
IMPORTANT:
|
||||
- If status is "rejected", do NOT retry.
|
||||
- If status is "not_found", relay the message to the user.
|
||||
- If status is "insufficient_permissions", inform user to re-authenticate.
|
||||
"""
|
||||
logger.info(
|
||||
f"delete_confluence_page called: page_title_or_id='{page_title_or_id}'"
|
||||
)
|
||||
|
||||
if db_session is None or workspace_id is None or user_id is None:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Confluence tool not properly configured.",
|
||||
}
|
||||
|
||||
try:
|
||||
metadata_service = ConfluenceToolMetadataService(db_session)
|
||||
context = await metadata_service.get_deletion_context(
|
||||
workspace_id, user_id, page_title_or_id
|
||||
)
|
||||
|
||||
if "error" in context:
|
||||
error_msg = context["error"]
|
||||
if context.get("auth_expired"):
|
||||
return {
|
||||
"status": "auth_error",
|
||||
"message": error_msg,
|
||||
"connector_id": context.get("connector_id"),
|
||||
"connector_type": "confluence",
|
||||
}
|
||||
if "not found" in error_msg.lower():
|
||||
return {"status": "not_found", "message": error_msg}
|
||||
return {"status": "error", "message": error_msg}
|
||||
|
||||
page_data = context["page"]
|
||||
page_id = page_data["page_id"]
|
||||
page_title = page_data.get("page_title", "")
|
||||
document_id = page_data["document_id"]
|
||||
connector_id_from_context = context.get("account", {}).get("id")
|
||||
|
||||
result = request_approval(
|
||||
action_type="confluence_page_deletion",
|
||||
tool_name="delete_confluence_page",
|
||||
params={
|
||||
"page_id": page_id,
|
||||
"connector_id": connector_id_from_context,
|
||||
"delete_from_kb": delete_from_kb,
|
||||
},
|
||||
context=context,
|
||||
)
|
||||
|
||||
if result.rejected:
|
||||
return {
|
||||
"status": "rejected",
|
||||
"message": "User declined. Do not retry or suggest alternatives.",
|
||||
}
|
||||
|
||||
final_page_id = result.params.get("page_id", page_id)
|
||||
final_connector_id = result.params.get(
|
||||
"connector_id", connector_id_from_context
|
||||
)
|
||||
final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
|
||||
|
||||
from sqlalchemy.future import select
|
||||
|
||||
from app.db import SearchSourceConnector, SearchSourceConnectorType
|
||||
|
||||
if not final_connector_id:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "No connector found for this page.",
|
||||
}
|
||||
|
||||
result = await db_session.execute(
|
||||
select(SearchSourceConnector).filter(
|
||||
SearchSourceConnector.id == final_connector_id,
|
||||
SearchSourceConnector.workspace_id == workspace_id,
|
||||
SearchSourceConnector.user_id == user_id,
|
||||
SearchSourceConnector.connector_type
|
||||
== SearchSourceConnectorType.CONFLUENCE_CONNECTOR,
|
||||
)
|
||||
)
|
||||
connector = result.scalars().first()
|
||||
if not connector:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Selected Confluence connector is invalid.",
|
||||
}
|
||||
|
||||
try:
|
||||
client = ConfluenceHistoryConnector(
|
||||
session=db_session, connector_id=final_connector_id
|
||||
)
|
||||
await client.delete_page(final_page_id)
|
||||
await client.close()
|
||||
except Exception as api_err:
|
||||
if (
|
||||
"http 403" in str(api_err).lower()
|
||||
or "status code 403" in str(api_err).lower()
|
||||
):
|
||||
try:
|
||||
connector.config = {**connector.config, "auth_expired": True}
|
||||
flag_modified(connector, "config")
|
||||
await db_session.commit()
|
||||
except Exception:
|
||||
pass
|
||||
return {
|
||||
"status": "insufficient_permissions",
|
||||
"connector_id": final_connector_id,
|
||||
"message": "This Confluence account needs additional permissions. Please re-authenticate in connector settings.",
|
||||
}
|
||||
raise
|
||||
|
||||
deleted_from_kb = False
|
||||
if final_delete_from_kb and document_id:
|
||||
try:
|
||||
from app.db import Document
|
||||
|
||||
doc_result = await db_session.execute(
|
||||
select(Document).filter(Document.id == document_id)
|
||||
)
|
||||
document = doc_result.scalars().first()
|
||||
if document:
|
||||
await db_session.delete(document)
|
||||
await db_session.commit()
|
||||
deleted_from_kb = True
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to delete document from KB: {e}")
|
||||
await db_session.rollback()
|
||||
|
||||
message = f"Confluence page '{page_title}' deleted successfully."
|
||||
if deleted_from_kb:
|
||||
message += " Also removed from the knowledge base."
|
||||
|
||||
return {
|
||||
"status": "success",
|
||||
"page_id": final_page_id,
|
||||
"deleted_from_kb": deleted_from_kb,
|
||||
"message": message,
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
from langgraph.errors import GraphInterrupt
|
||||
|
||||
if isinstance(e, GraphInterrupt):
|
||||
raise
|
||||
logger.error(f"Error deleting Confluence page: {e}", exc_info=True)
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Something went wrong while deleting the page.",
|
||||
}
|
||||
|
||||
return delete_confluence_page
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
"""``confluence`` native tools and (empty) permission ruleset.
|
||||
|
||||
Tools self-gate via :func:`request_approval` in their bodies.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.permissions import Ruleset
|
||||
|
||||
from .create_page import create_create_confluence_page_tool
|
||||
from .delete_page import create_delete_confluence_page_tool
|
||||
from .update_page import create_update_confluence_page_tool
|
||||
|
||||
NAME = "confluence"
|
||||
|
||||
RULESET = Ruleset(origin=NAME, rules=[])
|
||||
|
||||
|
||||
def load_tools(
|
||||
*, dependencies: dict[str, Any] | None = None, **kwargs: Any
|
||||
) -> list[BaseTool]:
|
||||
d = {**(dependencies or {}), **kwargs}
|
||||
common = {
|
||||
"db_session": d["db_session"],
|
||||
"workspace_id": d["workspace_id"],
|
||||
"user_id": d["user_id"],
|
||||
"connector_id": d.get("connector_id"),
|
||||
}
|
||||
return [
|
||||
create_create_confluence_page_tool(**common),
|
||||
create_update_confluence_page_tool(**common),
|
||||
create_delete_confluence_page_tool(**common),
|
||||
]
|
||||
|
|
@ -1,220 +0,0 @@
|
|||
import logging
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.tools import tool
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.orm.attributes import flag_modified
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
|
||||
request_approval,
|
||||
)
|
||||
from app.connectors.confluence_history import ConfluenceHistoryConnector
|
||||
from app.services.confluence import ConfluenceToolMetadataService
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def create_update_confluence_page_tool(
|
||||
db_session: AsyncSession | None = None,
|
||||
workspace_id: int | None = None,
|
||||
user_id: str | None = None,
|
||||
connector_id: int | None = None,
|
||||
):
|
||||
@tool
|
||||
async def update_confluence_page(
|
||||
page_title_or_id: str,
|
||||
new_title: str | None = None,
|
||||
new_content: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Update an existing Confluence page.
|
||||
|
||||
Use this tool when the user asks to modify or edit a Confluence page.
|
||||
|
||||
Args:
|
||||
page_title_or_id: The page title or ID to identify the page.
|
||||
new_title: Optional new title for the page.
|
||||
new_content: Optional new HTML/storage format content.
|
||||
|
||||
Returns:
|
||||
Dictionary with status and message.
|
||||
|
||||
IMPORTANT:
|
||||
- If status is "rejected", do NOT retry.
|
||||
- If status is "not_found", relay the message to the user.
|
||||
- If status is "insufficient_permissions", inform user to re-authenticate.
|
||||
"""
|
||||
logger.info(
|
||||
f"update_confluence_page called: page_title_or_id='{page_title_or_id}'"
|
||||
)
|
||||
|
||||
if db_session is None or workspace_id is None or user_id is None:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Confluence tool not properly configured.",
|
||||
}
|
||||
|
||||
try:
|
||||
metadata_service = ConfluenceToolMetadataService(db_session)
|
||||
context = await metadata_service.get_update_context(
|
||||
workspace_id, user_id, page_title_or_id
|
||||
)
|
||||
|
||||
if "error" in context:
|
||||
error_msg = context["error"]
|
||||
if context.get("auth_expired"):
|
||||
return {
|
||||
"status": "auth_error",
|
||||
"message": error_msg,
|
||||
"connector_id": context.get("connector_id"),
|
||||
"connector_type": "confluence",
|
||||
}
|
||||
if "not found" in error_msg.lower():
|
||||
return {"status": "not_found", "message": error_msg}
|
||||
return {"status": "error", "message": error_msg}
|
||||
|
||||
page_data = context["page"]
|
||||
page_id = page_data["page_id"]
|
||||
current_title = page_data["page_title"]
|
||||
current_body = page_data.get("body", "")
|
||||
current_version = page_data.get("version", 1)
|
||||
document_id = page_data.get("document_id")
|
||||
connector_id_from_context = context.get("account", {}).get("id")
|
||||
|
||||
result = request_approval(
|
||||
action_type="confluence_page_update",
|
||||
tool_name="update_confluence_page",
|
||||
params={
|
||||
"page_id": page_id,
|
||||
"document_id": document_id,
|
||||
"new_title": new_title,
|
||||
"new_content": new_content,
|
||||
"version": current_version,
|
||||
"connector_id": connector_id_from_context,
|
||||
},
|
||||
context=context,
|
||||
)
|
||||
|
||||
if result.rejected:
|
||||
return {
|
||||
"status": "rejected",
|
||||
"message": "User declined. Do not retry or suggest alternatives.",
|
||||
}
|
||||
|
||||
final_page_id = result.params.get("page_id", page_id)
|
||||
final_title = result.params.get("new_title", new_title) or current_title
|
||||
final_content = result.params.get("new_content", new_content)
|
||||
if final_content is None:
|
||||
final_content = current_body
|
||||
final_version = result.params.get("version", current_version)
|
||||
final_connector_id = result.params.get(
|
||||
"connector_id", connector_id_from_context
|
||||
)
|
||||
final_document_id = result.params.get("document_id", document_id)
|
||||
|
||||
from sqlalchemy.future import select
|
||||
|
||||
from app.db import SearchSourceConnector, SearchSourceConnectorType
|
||||
|
||||
if not final_connector_id:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "No connector found for this page.",
|
||||
}
|
||||
|
||||
result = await db_session.execute(
|
||||
select(SearchSourceConnector).filter(
|
||||
SearchSourceConnector.id == final_connector_id,
|
||||
SearchSourceConnector.workspace_id == workspace_id,
|
||||
SearchSourceConnector.user_id == user_id,
|
||||
SearchSourceConnector.connector_type
|
||||
== SearchSourceConnectorType.CONFLUENCE_CONNECTOR,
|
||||
)
|
||||
)
|
||||
connector = result.scalars().first()
|
||||
if not connector:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Selected Confluence connector is invalid.",
|
||||
}
|
||||
|
||||
try:
|
||||
client = ConfluenceHistoryConnector(
|
||||
session=db_session, connector_id=final_connector_id
|
||||
)
|
||||
api_result = await client.update_page(
|
||||
page_id=final_page_id,
|
||||
title=final_title,
|
||||
body=final_content,
|
||||
version_number=final_version + 1,
|
||||
)
|
||||
await client.close()
|
||||
except Exception as api_err:
|
||||
if (
|
||||
"http 403" in str(api_err).lower()
|
||||
or "status code 403" in str(api_err).lower()
|
||||
):
|
||||
try:
|
||||
connector.config = {**connector.config, "auth_expired": True}
|
||||
flag_modified(connector, "config")
|
||||
await db_session.commit()
|
||||
except Exception:
|
||||
pass
|
||||
return {
|
||||
"status": "insufficient_permissions",
|
||||
"connector_id": final_connector_id,
|
||||
"message": "This Confluence account needs additional permissions. Please re-authenticate in connector settings.",
|
||||
}
|
||||
raise
|
||||
|
||||
page_links = (
|
||||
api_result.get("_links", {}) if isinstance(api_result, dict) else {}
|
||||
)
|
||||
page_url = ""
|
||||
if page_links.get("base") and page_links.get("webui"):
|
||||
page_url = f"{page_links['base']}{page_links['webui']}"
|
||||
|
||||
kb_message_suffix = ""
|
||||
if final_document_id:
|
||||
try:
|
||||
from app.services.confluence import ConfluenceKBSyncService
|
||||
|
||||
kb_service = ConfluenceKBSyncService(db_session)
|
||||
kb_result = await kb_service.sync_after_update(
|
||||
document_id=final_document_id,
|
||||
page_id=final_page_id,
|
||||
user_id=user_id,
|
||||
workspace_id=workspace_id,
|
||||
)
|
||||
if kb_result["status"] == "success":
|
||||
kb_message_suffix = (
|
||||
" Your knowledge base has also been updated."
|
||||
)
|
||||
else:
|
||||
kb_message_suffix = (
|
||||
" The knowledge base will be updated in the next sync."
|
||||
)
|
||||
except Exception as kb_err:
|
||||
logger.warning(f"KB sync after update failed: {kb_err}")
|
||||
kb_message_suffix = (
|
||||
" The knowledge base will be updated in the next sync."
|
||||
)
|
||||
|
||||
return {
|
||||
"status": "success",
|
||||
"page_id": final_page_id,
|
||||
"page_url": page_url,
|
||||
"message": f"Confluence page '{final_title}' updated successfully.{kb_message_suffix}",
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
from langgraph.errors import GraphInterrupt
|
||||
|
||||
if isinstance(e, GraphInterrupt):
|
||||
raise
|
||||
logger.error(f"Error updating Confluence page: {e}", exc_info=True)
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Something went wrong while updating the page.",
|
||||
}
|
||||
|
||||
return update_confluence_page
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
"""``discord`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Tools self-gate inside their bodies via :func:`request_approval`; the
|
||||
empty :data:`tools.index.RULESET` is layered into a per-subagent
|
||||
:class:`PermissionMiddleware` for uniformity.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, RULESET, load_tools
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Handles discord tasks for this workspace."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=tools,
|
||||
ruleset=RULESET,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Specialist for messages in the user's Discord server.
|
||||
Use proactively when the user wants to read or send a Discord message.
|
||||
|
|
@ -1,115 +0,0 @@
|
|||
You are a Discord specialist for the user's connected Discord server.
|
||||
|
||||
## Vocabulary you must use precisely
|
||||
|
||||
- **Channel resolution via `list_discord_channels`** — the agent operates in a single connected Discord server (the guild is configured in the connector, not chosen by you). Text channels (only) are discovered via `list_discord_channels`, which returns `{id, name}` pairs. Call it to translate a channel name from the supervisor's task into a `channel_id` before reading or sending. Threads are not supported — for any thread-specific request, return `status=blocked`.
|
||||
- **Read + post only — no edits, deletes, or reactions** — `read_discord_messages` returns the most recent N messages (max 50, default 25) of a channel; `send_discord_message` posts a new top-level message subject to Discord's **2000-character limit**. Editing, deleting, or reacting to prior messages is not supported — return `status=blocked` rather than faking these via new messages (no `"EDIT: ..."` follow-ups, no `"Please delete this"` posts).
|
||||
|
||||
## Required inputs
|
||||
|
||||
**For every required input below, first try to infer it from the supervisor's task text** — extract channel names from `#mentions` or natural phrasing (`"the announcements channel"`, `"#general"`), and message content from any details the supervisor already provided. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read of the task.
|
||||
|
||||
- `list_discord_channels` — no inputs. Call it whenever you need to resolve a channel name to a `channel_id`.
|
||||
- `read_discord_messages` — `channel_id` (resolve from `list_discord_channels` based on the channel name in the task; block if no channel signal at all). Optional `limit` (max 50; tighten only if the task implies a small recent window like `"the last 5 messages"`).
|
||||
- `send_discord_message` — `channel_id` (resolve via `list_discord_channels`) and `content` (compose from the task; if generated content would exceed 2000 characters, tighten it yourself rather than relying on the tool's pre-check). Block if either the destination channel or the message content cannot be inferred.
|
||||
|
||||
## Outcome mapping
|
||||
|
||||
| Tool returns | Your `status` | `next_step` |
|
||||
|-------------------------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `success` with non-empty channels/messages | `success` | `null` |
|
||||
| `success` with `total: 0` (list returns no channels or read returns no messages) | `success` | `null` (surface `total: 0` in `evidence.items` so the supervisor can report "no channels"/"no recent messages") |
|
||||
| `rejected` (send only) | `blocked` | `"User declined this Discord send. Do not retry or suggest alternatives."` |
|
||||
| `auth_error` | `error` | `"The connected Discord bot token is invalid. Ask the user to update the Discord bot token in connector settings."` |
|
||||
| `error` | `error` | Relay the tool's `message` verbatim as `next_step`. |
|
||||
| tool raises / unknown | `error` | `"Discord tool failed unexpectedly. Ask the user to retry shortly."` |
|
||||
|
||||
Surface the tool's `message`, `channel_id`, and `message_id` inside `evidence` when the tool returned them. For `list_discord_channels` and `read_discord_messages`, set `evidence.items` to `{ "total": N }` and list the matched entries in `action_summary` (channel name or sender + timestamp + short text snippet; one line per entry; up to 10 entries, then `"...and N more"`). Never invent a field the tool did not return.
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1 — happy path send after channel resolution:**
|
||||
- *Supervisor task:* `"Post 'Standup in 5 min' to #announcements."`
|
||||
- *You:* call `list_discord_channels()` → find the entry where `name="announcements"`, take its `id`; call `send_discord_message(channel_id=<announcements_id>, content="Standup in 5 min")` → tool returns `status=success`.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"action_summary": "Posted a message to #announcements.",
|
||||
"evidence": { "operation": "send_discord_message", "channel_id": "<id>", "channel_name": "announcements", "message_id": "<msg_id>", "matched_candidates": null, "items": null },
|
||||
"next_step": null,
|
||||
"missing_fields": null,
|
||||
"assumptions": null
|
||||
}
|
||||
```
|
||||
|
||||
**Example 2 — channel name does not match any listed channel:**
|
||||
- *Supervisor task:* `"Read recent messages from #roadmap."`
|
||||
- *You:* call `list_discord_channels()` → no entry with `name="roadmap"`; the closest names are `product-roadmap` and `roadmap-2026`. Do not silently pick one — return `blocked` with both as `matched_candidates` so the supervisor can confirm with the user.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "No Discord channel exactly named 'roadmap' was found.",
|
||||
"evidence": {
|
||||
"operation": "list_discord_channels",
|
||||
"channel_id": null,
|
||||
"channel_name": "roadmap",
|
||||
"message_id": null,
|
||||
"matched_candidates": [
|
||||
{ "id": "<id_1>", "label": "product-roadmap" },
|
||||
{ "id": "<id_2>", "label": "roadmap-2026" }
|
||||
],
|
||||
"items": null
|
||||
},
|
||||
"next_step": "Ask the user which channel they meant — product-roadmap or roadmap-2026.",
|
||||
"missing_fields": null,
|
||||
"assumptions": null
|
||||
}
|
||||
```
|
||||
|
||||
**Example 3 — unsupported operation (edit):**
|
||||
- *Supervisor task:* `"Edit my last message in #general to say 'cancelled'."`
|
||||
- *You:* Discord edits are not supported by your tools. Do not call any tool. Do not post a new message like `"EDIT: cancelled"` — block.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Editing prior Discord messages is not supported.",
|
||||
"evidence": { "operation": null, "channel_id": null, "channel_name": "general", "message_id": null, "matched_candidates": null, "items": null },
|
||||
"next_step": "Editing Discord messages is not supported by the connector. Ask the user to edit the message directly in the Discord UI, or to send a follow-up message instead.",
|
||||
"missing_fields": null,
|
||||
"assumptions": null
|
||||
}
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Return **only** one JSON object (no markdown or prose outside it):
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"operation": "list_discord_channels" | "read_discord_messages" | "send_discord_message" | null,
|
||||
"channel_id": string | null,
|
||||
"channel_name": string | null,
|
||||
"message_id": string | null,
|
||||
"matched_candidates": [ { "id": string, "label": string } ] | null,
|
||||
"items": object | null
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
```
|
||||
|
||||
<include snippet="output_contract_base"/>
|
||||
|
||||
<include snippet="verifiable_handle"/>
|
||||
|
||||
Resolve before you call; verify before you send; map every tool outcome faithfully.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
from .list_channels import create_list_discord_channels_tool
|
||||
from .read_messages import create_read_discord_messages_tool
|
||||
from .send_message import create_send_discord_message_tool
|
||||
|
||||
__all__ = [
|
||||
"create_list_discord_channels_tool",
|
||||
"create_read_discord_messages_tool",
|
||||
"create_send_discord_message_tool",
|
||||
]
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
"""Builds Discord REST API auth headers for connector-backed tools."""
|
||||
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.future import select
|
||||
|
||||
from app.config import config
|
||||
from app.db import SearchSourceConnector, SearchSourceConnectorType
|
||||
from app.utils.oauth_security import TokenEncryption
|
||||
|
||||
DISCORD_API = "https://discord.com/api/v10"
|
||||
|
||||
|
||||
async def get_discord_connector(
|
||||
db_session: AsyncSession,
|
||||
workspace_id: int,
|
||||
user_id: str,
|
||||
) -> SearchSourceConnector | None:
|
||||
result = await db_session.execute(
|
||||
select(SearchSourceConnector).filter(
|
||||
SearchSourceConnector.workspace_id == workspace_id,
|
||||
SearchSourceConnector.user_id == user_id,
|
||||
SearchSourceConnector.connector_type
|
||||
== SearchSourceConnectorType.DISCORD_CONNECTOR,
|
||||
)
|
||||
)
|
||||
return result.scalars().first()
|
||||
|
||||
|
||||
def get_bot_token(connector: SearchSourceConnector) -> str:
|
||||
"""Extract and decrypt the bot token from connector config."""
|
||||
cfg = dict(connector.config)
|
||||
if cfg.get("_token_encrypted") and config.SECRET_KEY:
|
||||
enc = TokenEncryption(config.SECRET_KEY)
|
||||
if cfg.get("bot_token"):
|
||||
cfg["bot_token"] = enc.decrypt_token(cfg["bot_token"])
|
||||
token = cfg.get("bot_token")
|
||||
if not token:
|
||||
raise ValueError("Discord bot token not found in connector config.")
|
||||
return token
|
||||
|
||||
|
||||
def get_guild_id(connector: SearchSourceConnector) -> str | None:
|
||||
return connector.config.get("guild_id")
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
"""``discord`` native tools and (empty) permission ruleset.
|
||||
|
||||
Tools self-gate via :func:`request_approval` in their bodies.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.shared.permissions import Ruleset
|
||||
|
||||
from .list_channels import create_list_discord_channels_tool
|
||||
from .read_messages import create_read_discord_messages_tool
|
||||
from .send_message import create_send_discord_message_tool
|
||||
|
||||
NAME = "discord"
|
||||
|
||||
RULESET = Ruleset(origin=NAME, rules=[])
|
||||
|
||||
|
||||
def load_tools(
|
||||
*, dependencies: dict[str, Any] | None = None, **kwargs: Any
|
||||
) -> list[BaseTool]:
|
||||
d = {**(dependencies or {}), **kwargs}
|
||||
common = {
|
||||
"db_session": d["db_session"],
|
||||
"workspace_id": d["workspace_id"],
|
||||
"user_id": d["user_id"],
|
||||
}
|
||||
return [
|
||||
create_list_discord_channels_tool(**common),
|
||||
create_read_discord_messages_tool(**common),
|
||||
create_send_discord_message_tool(**common),
|
||||
]
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
import logging
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from langchain_core.tools import tool
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from ._auth import DISCORD_API, get_bot_token, get_discord_connector, get_guild_id
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def create_list_discord_channels_tool(
|
||||
db_session: AsyncSession | None = None,
|
||||
workspace_id: int | None = None,
|
||||
user_id: str | None = None,
|
||||
):
|
||||
@tool
|
||||
async def list_discord_channels() -> dict[str, Any]:
|
||||
"""List text channels in the connected Discord server.
|
||||
|
||||
Returns:
|
||||
Dictionary with status and a list of channels (id, name).
|
||||
"""
|
||||
if db_session is None or workspace_id is None or user_id is None:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Discord tool not properly configured.",
|
||||
}
|
||||
|
||||
try:
|
||||
connector = await get_discord_connector(db_session, workspace_id, user_id)
|
||||
if not connector:
|
||||
return {"status": "error", "message": "No Discord connector found."}
|
||||
|
||||
guild_id = get_guild_id(connector)
|
||||
if not guild_id:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "No guild ID in Discord connector config.",
|
||||
}
|
||||
|
||||
token = get_bot_token(connector)
|
||||
|
||||
async with httpx.AsyncClient() as client:
|
||||
resp = await client.get(
|
||||
f"{DISCORD_API}/guilds/{guild_id}/channels",
|
||||
headers={"Authorization": f"Bot {token}"},
|
||||
timeout=15.0,
|
||||
)
|
||||
|
||||
if resp.status_code == 401:
|
||||
return {
|
||||
"status": "auth_error",
|
||||
"message": "Discord bot token is invalid.",
|
||||
"connector_type": "discord",
|
||||
}
|
||||
if resp.status_code != 200:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": f"Discord API error: {resp.status_code}",
|
||||
}
|
||||
|
||||
# Type 0 = text channel
|
||||
channels = [
|
||||
{"id": ch["id"], "name": ch["name"]}
|
||||
for ch in resp.json()
|
||||
if ch.get("type") == 0
|
||||
]
|
||||
return {
|
||||
"status": "success",
|
||||
"guild_id": guild_id,
|
||||
"channels": channels,
|
||||
"total": len(channels),
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
from langgraph.errors import GraphInterrupt
|
||||
|
||||
if isinstance(e, GraphInterrupt):
|
||||
raise
|
||||
logger.error("Error listing Discord channels: %s", e, exc_info=True)
|
||||
return {"status": "error", "message": "Failed to list Discord channels."}
|
||||
|
||||
return list_discord_channels
|
||||
|
|
@ -1,98 +0,0 @@
|
|||
import logging
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from langchain_core.tools import tool
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from ._auth import DISCORD_API, get_bot_token, get_discord_connector
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def create_read_discord_messages_tool(
|
||||
db_session: AsyncSession | None = None,
|
||||
workspace_id: int | None = None,
|
||||
user_id: str | None = None,
|
||||
):
|
||||
@tool
|
||||
async def read_discord_messages(
|
||||
channel_id: str,
|
||||
limit: int = 25,
|
||||
) -> dict[str, Any]:
|
||||
"""Read recent messages from a Discord text channel.
|
||||
|
||||
Args:
|
||||
channel_id: The Discord channel ID (from list_discord_channels).
|
||||
limit: Number of messages to fetch (default 25, max 50).
|
||||
|
||||
Returns:
|
||||
Dictionary with status and a list of messages including
|
||||
id, author, content, timestamp.
|
||||
"""
|
||||
if db_session is None or workspace_id is None or user_id is None:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Discord tool not properly configured.",
|
||||
}
|
||||
|
||||
limit = min(limit, 50)
|
||||
|
||||
try:
|
||||
connector = await get_discord_connector(db_session, workspace_id, user_id)
|
||||
if not connector:
|
||||
return {"status": "error", "message": "No Discord connector found."}
|
||||
|
||||
token = get_bot_token(connector)
|
||||
|
||||
async with httpx.AsyncClient() as client:
|
||||
resp = await client.get(
|
||||
f"{DISCORD_API}/channels/{channel_id}/messages",
|
||||
headers={"Authorization": f"Bot {token}"},
|
||||
params={"limit": limit},
|
||||
timeout=15.0,
|
||||
)
|
||||
|
||||
if resp.status_code == 401:
|
||||
return {
|
||||
"status": "auth_error",
|
||||
"message": "Discord bot token is invalid.",
|
||||
"connector_type": "discord",
|
||||
}
|
||||
if resp.status_code == 403:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Bot lacks permission to read this channel.",
|
||||
}
|
||||
if resp.status_code != 200:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": f"Discord API error: {resp.status_code}",
|
||||
}
|
||||
|
||||
messages = [
|
||||
{
|
||||
"id": m["id"],
|
||||
"author": m.get("author", {}).get("username", "Unknown"),
|
||||
"content": m.get("content", ""),
|
||||
"timestamp": m.get("timestamp", ""),
|
||||
}
|
||||
for m in resp.json()
|
||||
]
|
||||
|
||||
return {
|
||||
"status": "success",
|
||||
"channel_id": channel_id,
|
||||
"messages": messages,
|
||||
"total": len(messages),
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
from langgraph.errors import GraphInterrupt
|
||||
|
||||
if isinstance(e, GraphInterrupt):
|
||||
raise
|
||||
logger.error("Error reading Discord messages: %s", e, exc_info=True)
|
||||
return {"status": "error", "message": "Failed to read Discord messages."}
|
||||
|
||||
return read_discord_messages
|
||||
|
|
@ -1,117 +0,0 @@
|
|||
import logging
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from langchain_core.tools import tool
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
|
||||
request_approval,
|
||||
)
|
||||
|
||||
from ._auth import DISCORD_API, get_bot_token, get_discord_connector
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def create_send_discord_message_tool(
|
||||
db_session: AsyncSession | None = None,
|
||||
workspace_id: int | None = None,
|
||||
user_id: str | None = None,
|
||||
):
|
||||
@tool
|
||||
async def send_discord_message(
|
||||
channel_id: str,
|
||||
content: str,
|
||||
) -> dict[str, Any]:
|
||||
"""Send a message to a Discord text channel.
|
||||
|
||||
Args:
|
||||
channel_id: The Discord channel ID (from list_discord_channels).
|
||||
content: The message text (max 2000 characters).
|
||||
|
||||
Returns:
|
||||
Dictionary with status, message_id on success.
|
||||
|
||||
IMPORTANT:
|
||||
- If status is "rejected", the user explicitly declined. Do NOT retry.
|
||||
"""
|
||||
if db_session is None or workspace_id is None or user_id is None:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Discord tool not properly configured.",
|
||||
}
|
||||
|
||||
if len(content) > 2000:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Message exceeds Discord's 2000-character limit.",
|
||||
}
|
||||
|
||||
try:
|
||||
connector = await get_discord_connector(db_session, workspace_id, user_id)
|
||||
if not connector:
|
||||
return {"status": "error", "message": "No Discord connector found."}
|
||||
|
||||
result = request_approval(
|
||||
action_type="discord_send_message",
|
||||
tool_name="send_discord_message",
|
||||
params={"channel_id": channel_id, "content": content},
|
||||
context={"connector_id": connector.id},
|
||||
)
|
||||
|
||||
if result.rejected:
|
||||
return {
|
||||
"status": "rejected",
|
||||
"message": "User declined. Message was not sent.",
|
||||
}
|
||||
|
||||
final_content = result.params.get("content", content)
|
||||
final_channel = result.params.get("channel_id", channel_id)
|
||||
|
||||
token = get_bot_token(connector)
|
||||
|
||||
async with httpx.AsyncClient() as client:
|
||||
resp = await client.post(
|
||||
f"{DISCORD_API}/channels/{final_channel}/messages",
|
||||
headers={
|
||||
"Authorization": f"Bot {token}",
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
json={"content": final_content},
|
||||
timeout=15.0,
|
||||
)
|
||||
|
||||
if resp.status_code == 401:
|
||||
return {
|
||||
"status": "auth_error",
|
||||
"message": "Discord bot token is invalid.",
|
||||
"connector_type": "discord",
|
||||
}
|
||||
if resp.status_code == 403:
|
||||
return {
|
||||
"status": "error",
|
||||
"message": "Bot lacks permission to send messages in this channel.",
|
||||
}
|
||||
if resp.status_code not in (200, 201):
|
||||
return {
|
||||
"status": "error",
|
||||
"message": f"Discord API error: {resp.status_code}",
|
||||
}
|
||||
|
||||
msg_data = resp.json()
|
||||
return {
|
||||
"status": "success",
|
||||
"message_id": msg_data.get("id"),
|
||||
"message": f"Message sent to channel {final_channel}.",
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
from langgraph.errors import GraphInterrupt
|
||||
|
||||
if isinstance(e, GraphInterrupt):
|
||||
raise
|
||||
logger.error("Error sending Discord message: %s", e, exc_info=True)
|
||||
return {"status": "error", "message": "Failed to send Discord message."}
|
||||
|
||||
return send_discord_message
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
"""``gmail`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Tools self-gate inside their bodies via :func:`request_approval`; the
|
||||
empty :data:`tools.index.RULESET` is layered into a per-subagent
|
||||
:class:`PermissionMiddleware` for uniformity.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, RULESET, load_tools
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Handles gmail tasks for this workspace."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=tools,
|
||||
ruleset=RULESET,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
Specialist for messages in the user's Gmail inbox.
|
||||
Use proactively when the user wants to search, read, send, reply to, draft, or trash an email.
|
||||
Email-only conversations belong here, including discussions about meetings that do not reserve a time slot.
|
||||
|
|
@ -1,121 +0,0 @@
|
|||
You are a Gmail specialist for the user's connected Gmail mailbox.
|
||||
|
||||
## Vocabulary you must use precisely
|
||||
|
||||
- **Search-then-act for reading** — `read_gmail_email` accepts only a `message_id`. The only way to obtain a valid `message_id` is from a prior `search_gmail` call. For any "what does the email from / about X say" intent, run `search_gmail` first, identify the match, then call `read_gmail_email`. Never invent or guess a `message_id`.
|
||||
- **Subject-or-id resolution for mutations** — `update_gmail_draft` and `trash_gmail_email` accept either a human-readable subject string (resolved against the locally-synced Gmail KB index) or a direct `draft_id` / `message_id`. Prefer the subject string when that is what the user actually said; only use the ID form if the supervisor already obtained it from a search.
|
||||
- **Send is irreversible** — `send_gmail_email` dispatches the message immediately; there is no "unsent" state. `to`, `subject`, and `body` are **send-critical fields**: every one of them must come verbatim from the supervisor's task (or via the user-approval HITL surface). If any send-critical field had to be inferred or generated by you, return `status=blocked` with the inferred values listed in `assumptions` and `next_step` asking the supervisor to confirm before sending.
|
||||
- **Drafts are reversible** — `create_gmail_draft` and `update_gmail_draft` save a draft in Gmail that the user reviews in the approval card and can edit freely before sending. Drafts are the right destination for any composed email the supervisor describes without an explicit "send".
|
||||
- **Verb dispatch (send vs. draft)** — task verbs `send`, `email <person>`, `reply and send` → `send_gmail_email`. Task verbs `draft`, `compose`, `prepare`, `write up` → `create_gmail_draft`. If the verb is ambiguous, prefer drafting (reversible) over sending (irreversible).
|
||||
- **Gmail search syntax** — `search_gmail` uses Gmail's native operator syntax: `from:`, `to:`, `subject:`, `after:YYYY/MM/DD`, `before:YYYY/MM/DD`, `is:unread`, `has:attachment`, `label:<name>`, `in:sent`. Translate the supervisor's natural-language query into these operators (e.g. `"unread emails from Alice last week"` → `from:alice@... is:unread after:<date>`). Resolve relative dates against the runtime timestamp.
|
||||
|
||||
## Required inputs
|
||||
|
||||
**For every required input below, first try to infer it from the supervisor's task text** — extract recipients from phrases like `"to Alice"` / `"email bob@x.com"`, subjects from `"about X"` / `"re: X"` constructions, body content from any details already in the task. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
|
||||
|
||||
- `send_gmail_email` — `to`, `subject`, `body`. **Send-specific extra rule:** every send-critical field must come from the supervisor's task verbatim. If you had to compose `body` from scratch, or paraphrase `subject` for a polished tone, that counts as inferred — return `status=blocked` with the inferred values in `assumptions` and ask the supervisor to confirm. Do not call `send_gmail_email` with anything inferred. `cc` / `bcc` are optional and may be omitted unless the user named them.
|
||||
- `create_gmail_draft` — `to`, `subject`, `body`. Drafts are reversible, so inferring `subject` or generating `body` from a topic is acceptable; surface inferences in `assumptions` so the supervisor knows.
|
||||
- `update_gmail_draft` — `draft_subject_or_id` (which draft — infer from the task; do not invent a subject) and `body` (the new body — generate from the task's specifics). Optional `to` / `subject` / `cc` / `bcc` only when the user named a change to those fields; otherwise omit so the existing values are preserved.
|
||||
- `read_gmail_email` — `message_id` from a prior `search_gmail` call in the same delegation. If you do not yet have a `message_id`, run `search_gmail` first.
|
||||
- `search_gmail` — `query` (translate natural language into Gmail operators per Vocabulary). `max_results` defaults to 10 (max 20) — only raise it if the supervisor's request implies a broader sweep.
|
||||
- `trash_gmail_email` — `email_subject_or_id` (which email — infer from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove the email from the knowledge base as well; otherwise leave it `false`.
|
||||
|
||||
## Outcome mapping
|
||||
|
||||
| Tool returns | Your `status` | `next_step` |
|
||||
|-----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `success` | `success` | `null` |
|
||||
| `success` with `total: 0` (`search_gmail` only) | `blocked` | `"No emails matched the query '<query>'. Ask the user to widen the criteria or provide more specifics."` |
|
||||
| `rejected` | `blocked` | `"User declined this Gmail action. Do not retry or suggest alternatives."` |
|
||||
| `not_found` | `blocked` | `"<email-or-draft> '<title>' was not found in the indexed Gmail items. Ask the user to verify the subject or wait for the next KB sync."` |
|
||||
| `auth_error` | `error` | `"The connected Gmail account needs re-authentication. Ask the user to re-authenticate Gmail in connector settings."` |
|
||||
| `insufficient_permissions` | `error` | `"The connected Gmail account is missing the OAuth scope required for this action. Ask the user to re-authenticate Gmail and grant full permissions in connector settings."` |
|
||||
| `error` | `error` | Relay the tool's `message` verbatim as `next_step`. |
|
||||
| tool raises / unknown | `error` | `"Gmail tool failed unexpectedly. Ask the user to retry shortly."` |
|
||||
|
||||
Surface the tool's `message_id`, `thread_id`, `draft_id`, `subject`, and recipient fields inside `evidence` when the tool returned them. For `search_gmail`, set `evidence.items` to `{ "total": N }` and list the matched emails in `action_summary` (sender, subject, date; one line per email; up to 10 entries, then `"...and N more"`). Never invent a field the tool did not return.
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1 — search-then-read (multi-step happy path):**
|
||||
- *Supervisor task:* `"What did Alice say in her email about the launch plan last week?"`
|
||||
- *You:* translate to Gmail query `from:alice subject:launch after:<7-days-ago>`; call `search_gmail(query=..., max_results=10)`. Tool returns `total=1` with one email. Extract its `message_id` and call `read_gmail_email(message_id=...)`. Tool returns `status=success` with the markdown body.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"action_summary": "Found and read Alice's email 'Re: Launch plan v2' from <date>; full body returned in evidence.items.body.",
|
||||
"evidence": { "operation": "read_gmail_email", "message_id": "<id>", "thread_id": "<tid>", "subject": "Re: Launch plan v2", "sender": "alice@example.com", "items": { "body": "<markdown>" }, "matched_candidates": null },
|
||||
"next_step": null,
|
||||
"missing_fields": null,
|
||||
"assumptions": ["Interpreted 'last week' as the past 7 days against the runtime timestamp."]
|
||||
}
|
||||
```
|
||||
|
||||
**Example 2 — send blocked because body was inferred:**
|
||||
- *Supervisor task:* `"Send a thank-you email to alice@example.com."`
|
||||
- *You:* `to=alice@example.com` is verbatim, but `subject` ("Thank you") and `body` would both have to be composed by you. Send is irreversible — do not dispatch inferred content. Do not call `send_gmail_email`.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Cannot send: subject and body would be inferred, and send is irreversible.",
|
||||
"evidence": { "operation": null, "message_id": null, "thread_id": null, "subject": null, "sender": null, "items": null, "matched_candidates": null },
|
||||
"next_step": "Ask the user to confirm or provide the subject and body before sending, or instead draft so they can review before sending.",
|
||||
"missing_fields": ["subject", "body"],
|
||||
"assumptions": null
|
||||
}
|
||||
```
|
||||
|
||||
**Example 3 — search returns zero results:**
|
||||
- *Supervisor task:* `"Trash the email from Bob about the cancelled Q3 launch."`
|
||||
- *You:* before trashing, locate it. Call `search_gmail(query="from:bob subject:Q3 launch")` → tool returns `status=success, total=0`. No target to trash.
|
||||
- *Output:*
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "No emails matched 'from Bob about cancelled Q3 launch'.",
|
||||
"evidence": { "operation": "search_gmail", "message_id": null, "thread_id": null, "subject": null, "sender": null, "items": { "emails": [], "total": 0 }, "matched_candidates": null },
|
||||
"next_step": "Ask the user to widen the search (different sender, broader date range, or part of the actual subject line) or confirm the email exists in this account.",
|
||||
"missing_fields": null,
|
||||
"assumptions": ["Interpreted 'about the cancelled Q3 launch' as a subject-line filter; could also match body text only."]
|
||||
}
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Return **only** one JSON object (no markdown or prose outside it):
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"operation": "send_gmail_email" | "create_gmail_draft" | "update_gmail_draft" | "read_gmail_email" | "search_gmail" | "trash_gmail_email" | null,
|
||||
"message_id": string | null,
|
||||
"thread_id": string | null,
|
||||
"draft_id": string | null,
|
||||
"subject": string | null,
|
||||
"sender": string | null,
|
||||
"recipients": string[] | null,
|
||||
"matched_candidates": [ { "id": string, "label": string } ] | null,
|
||||
"items": object | null
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
```
|
||||
|
||||
<include snippet="output_contract_base"/>
|
||||
|
||||
Route-specific rules:
|
||||
- For `search_gmail` results, set `evidence.items` to `{ "total": N }` and list the matched emails in `action_summary` (sender, subject, date; up to 10 entries, then `"...and N more"`).
|
||||
- For ambiguous matches across `update_gmail_draft` / `trash_gmail_email` / `read_gmail_email`, populate `evidence.matched_candidates` with up to 5 options (`id` + `label`).
|
||||
|
||||
<include snippet="verifiable_handle"/>
|
||||
|
||||
Infer before you call; verify before you send; map every tool outcome faithfully.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
"""``jira`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
|
||||
|
||||
Tools come exclusively from MCP. The connector's own approval ruleset is
|
||||
declared in :data:`tools.index.RULESET`; the orchestrator layers it into
|
||||
a per-subagent :class:`PermissionMiddleware`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.language_models import BaseChatModel
|
||||
from langchain_core.tools import BaseTool
|
||||
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.md_file_reader import (
|
||||
read_md_file,
|
||||
)
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
|
||||
from app.agents.chat.multi_agent_chat.subagents.shared.subagent_builder import (
|
||||
pack_subagent,
|
||||
)
|
||||
|
||||
from .tools.index import NAME, RULESET
|
||||
|
||||
|
||||
def build_subagent(
|
||||
*,
|
||||
dependencies: dict[str, Any],
|
||||
model: BaseChatModel | None = None,
|
||||
middleware_stack: dict[str, Any] | None = None,
|
||||
mcp_tools: list[BaseTool] | None = None,
|
||||
) -> SurfSenseSubagentSpec:
|
||||
description = (
|
||||
read_md_file(__package__, "description").strip()
|
||||
or "Handles jira tasks for this workspace."
|
||||
)
|
||||
system_prompt = read_md_file(__package__, "system_prompt").strip()
|
||||
return pack_subagent(
|
||||
name=NAME,
|
||||
description=description,
|
||||
system_prompt=system_prompt,
|
||||
tools=list(mcp_tools or []),
|
||||
ruleset=RULESET,
|
||||
dependencies=dependencies,
|
||||
model=model,
|
||||
middleware_stack=middleware_stack,
|
||||
)
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Specialist for issues and projects in the user's Jira.
|
||||
Use proactively when the user wants to find, create, or update a Jira issue, assign it, or transition it between workflow states.
|
||||
|
|
@ -1,122 +0,0 @@
|
|||
You are a Jira specialist for the user's connected Atlassian Jira instance(s).
|
||||
|
||||
Jira vocabulary:
|
||||
- **Site / `cloudId`**: a user may have access to multiple Atlassian sites. Every project/issue operation is scoped to one `cloudId`. Look up the user's accessible Atlassian sites if the request leaves the site unspecified.
|
||||
- **Project key**: `<ABC>` (e.g. `ENG`, `OPS`). Stable per project; used to build issue keys.
|
||||
- **Issue key**: `<PROJECT_KEY>-<NUMBER>` (e.g. `ENG-42`). User-facing and stable; prefer it in `action_summary`.
|
||||
- **Workflow & transitions**: Jira does *not* let you set a status directly. Each issue's workflow exposes a list of currently-available transitions (each with its own `transitionId`), and only those transitions can be applied. The set of available transitions depends on the issue's current status and is project-/workflow-specific — there is no universal mapping from a status name to a transition.
|
||||
- **Issue type**: per-project. Available types and required fields vary per project — there is no global list. Look up the project's actual issue types (and their required fields) before relying on a type name.
|
||||
- **Priority**: per-project string names (not integers, not a fixed scheme). Different Jira projects use different priority labels and may add or remove options. Look up the target project's actual priorities before setting one.
|
||||
- **Assignee**: Jira identifies users by opaque `accountId`, never by display name or email. Map the display name or email to an `accountId` before assigning.
|
||||
- **Reporter**: defaults to the API caller's user; only override when the request explicitly asks for a different reporter.
|
||||
- **JQL**: Jira Query Language — the canonical way to filter issues. The syntax (field operators `=` `!=` `~` `>` `<` `in`, functions like `currentUser()`, date math like `-7d`) is stable. The **values** you put into JQL (status names, priority labels, issue-type names, project keys, account IDs) are not — look those up rather than guessing.
|
||||
- **Custom fields**: many Jira projects mandate custom fields on create (epic link, sprint, story points, etc.). Required fields are project-/issue-type-specific.
|
||||
|
||||
When invoked:
|
||||
1. Read the supervisor's request, then read the runtime tool list to learn what information you can fetch and which mutations are available.
|
||||
2. Plan the minimum chain of lookups needed to resolve any identifier, name, scope, or required field the request leaves unspecified (site / project / issue / transition / user / required fields, etc.).
|
||||
3. Execute the planned lookups, then the requested mutation (if any), then return.
|
||||
|
||||
Resolution principle (the core behaviour):
|
||||
**Proactively look up any identifier, name, value, or scope the request leaves unspecified — `cloudId`, project keys, issue keys, `accountId`s, `transitionId`s, custom-field values, anything else — using the available tools instead of asking the supervisor.** Most user requests reference targets by title, description, or paraphrase, not by key. Search by JQL or by the relevant metadata.
|
||||
|
||||
When a lookup for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 candidates in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. The supervisor will disambiguate and redelegate.
|
||||
|
||||
When a lookup returns zero matches for a slot the request requires, return `status=blocked` with a `next_step` suggesting alternative filters.
|
||||
|
||||
Mutation guardrails:
|
||||
- Resolve every required Jira value (`cloudId`, `projectKey`, `issueKey`, `transitionId`, `accountId`, custom-field values) by looking it up before calling a mutation tool. Mutations have chained dependencies — `cloudId` enables project lookup; project lookup enables issue-type and required-field resolution; issue lookup enables transition resolution.
|
||||
- Never set status directly. To change an issue's status, look up that issue's currently-available transitions and apply the matching `transitionId`. If the user-requested target status is not in the available transitions, return `status=blocked` and surface the available transitions in `evidence.matched_candidates`.
|
||||
- Never invent `cloudId`s, keys, `accountId`s, `transitionId`s, custom-field values, priority labels, issue-type names, or mutation outcomes. Every field in `evidence` must come from a tool result.
|
||||
- For create operations, look up the target issue type's required-field schema before assuming `summary`/`issueType` is enough — many projects mandate priority, due date, or custom fields.
|
||||
- Confirm the mutation tool returned a success response before claiming success. If the mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
|
||||
- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
|
||||
|
||||
Failure handling:
|
||||
- Tool failure: return `status=error`, place the underlying error message in `action_summary`, and put a concise recovery in `next_step`.
|
||||
- No useful results after reasonable narrowing/broadening: return `status=blocked` with filter / JQL suggestions in `next_step`.
|
||||
|
||||
<example>
|
||||
Supervisor: "Find issues assigned to me with status 'In Progress'."
|
||||
1. JQL search with `assignee = currentUser() AND status = "In Progress"`.
|
||||
2. Return `status=success` with `evidence.items` set to `{ "total": N }` and the matched issues listed in `action_summary` (issue key, summary, status, assignee; one line per issue; up to 10 entries, then `"...and N more"`).
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Supervisor: "Create a Bug 'Login fails on Safari' in the Mobile project."
|
||||
1. Look up accessible sites → multiple sites are connected to the user. The request gives no signal pointing to one.
|
||||
2. Cannot pick the `cloudId`. Return:
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Need to know which Atlassian site holds the Mobile project.",
|
||||
"evidence": {
|
||||
"title": "Login fails on Safari",
|
||||
"matched_candidates": [
|
||||
{ "id": "cloud_acme", "label": "acme.atlassian.net" },
|
||||
{ "id": "cloud_acme_eu", "label": "acme-eu.atlassian.net" }
|
||||
]
|
||||
},
|
||||
"next_step": "Confirm which Atlassian site, then redelegate.",
|
||||
"missing_fields": ["site"]
|
||||
}
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Supervisor: "Move `PROJ-123` to Done and assign it to Sam."
|
||||
1. Look up `PROJ-123` → exists; current status `In Review`; project `PROJ`.
|
||||
2. Look up available transitions for `PROJ-123` → `[ "Code Review → Done" (id=51), "Code Review → Cancelled" (id=61) ]`. `Done` is reachable via transition id `51`.
|
||||
3. Look up users named "Sam" → two matches (`accountId=acc_sam1`, `accountId=acc_sam2`).
|
||||
4. Cannot confidently pick the assignee. Return:
|
||||
{
|
||||
"status": "blocked",
|
||||
"action_summary": "Issue resolved (PROJ-123). Transition to Done resolved (id 51). Two users match 'Sam'.",
|
||||
"evidence": {
|
||||
"identifier": "PROJ-123",
|
||||
"title": "Refactor auth module",
|
||||
"transition_id": "51",
|
||||
"matched_candidates": [
|
||||
{ "id": "acc_sam1", "label": "Sam Carter <sam.carter@…>" },
|
||||
{ "id": "acc_sam2", "label": "Sam Lopez <sam.lopez@…>" }
|
||||
]
|
||||
},
|
||||
"next_step": "Confirm which Sam, then redelegate.",
|
||||
"missing_fields": ["assignee"]
|
||||
}
|
||||
</example>
|
||||
|
||||
<output_contract>
|
||||
Return **only** one JSON object (no markdown, no prose):
|
||||
{
|
||||
"status": "success" | "partial" | "blocked" | "error",
|
||||
"action_summary": string,
|
||||
"evidence": {
|
||||
"site": string | null,
|
||||
"cloud_id": string | null,
|
||||
"project_key": string | null,
|
||||
"identifier": string | null,
|
||||
"issue_id": string | null,
|
||||
"title": string | null,
|
||||
"issue_type": string | null,
|
||||
"status": string | null,
|
||||
"transition_id": string | null,
|
||||
"assignee": string | null,
|
||||
"priority": string | null,
|
||||
"url": string | null,
|
||||
"matched_candidates": [
|
||||
{ "id": string, "label": string }
|
||||
] | null,
|
||||
"items": object | null
|
||||
},
|
||||
"next_step": string | null,
|
||||
"missing_fields": string[] | null,
|
||||
"assumptions": string[] | null
|
||||
}
|
||||
<include snippet="output_contract_base"/>
|
||||
Route-specific rules:
|
||||
- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label` — works for any kind of candidate: site, project, issue, user, transition, etc.).
|
||||
- For discovery-only queries (lists), set `evidence.items` to `{ "total": N }` and list the matched items in `action_summary` (issue key, summary, status, assignee; up to 10 entries, then `"...and N more"`).
|
||||
</output_contract>
|
||||
|
||||
<include snippet="verifiable_handle"/>
|
||||
|
||||
Discover before you mutate; never guess identifiers, transitions, or required fields.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
"""Jira route: native tool factories are empty; MCP supplies tools when configured."""
|
||||
|
||||
__all__: list[str] = []
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue