From 4e91b5d0478f5051f8cddd21b3fc0921542a0a9c Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 2 Jul 2026 07:05:54 +0530 Subject: [PATCH 1/3] =?UTF-8?q?docs(m106):=20Slack-resident=20channel=20bo?= =?UTF-8?q?t=20=E2=80=94=20changelog,=20error=20codes,=20trigger=20sources?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New Jul 02, 2026 changelog entry for the Slack connector: dashboard OAuth connect, one resident fleet per channel, in-thread answers, channel-scoped memory, and the recent-thread re-read. Error-code reference gains the five UZ-SLK rows (statuses from the server registry) and UZ-CONN-001 is generalized beyond GitHub now that two providers share the connect flow. concepts.mdx trigger sources go three → four with the Slack mention. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/error-codes.mdx | 7 ++++++- changelog.mdx | 20 ++++++++++++++++++++ concepts.mdx | 3 ++- 3 files changed, 28 insertions(+), 2 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 1dae07e..8637e72 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -181,11 +181,16 @@ Onboarding a Fleet template (the SKILL.md/TRIGGER.md package behind a Fleet) and | Code | HTTP | Title | Common Causes | |---|---|---|---| -| `UZ-CONN-001` | 503 | Connector not configured | GitHub connect is unavailable on this deployment — the platform App slug or signing secret is unset. An operator must register the GitHub App and populate the admin vault before fleets can connect. | +| `UZ-CONN-001` | 503 | Connector not configured | Connect is unavailable for this provider on this deployment — the platform app credentials (GitHub App slug / Slack app secrets) are unset. An operator must register the provider app and populate the admin vault before workspaces can connect. | | `UZ-CONN-002` | 400 | Invalid connect state | The connect callback's `state` was missing, forged, expired, or already used. Start the connect again from the dashboard — each attempt issues a fresh single-use state. | | `UZ-CRED-001` | 404 | Integration not connected | No connected integration matches this id for the fleet's workspace. Connect it first (e.g. GitHub via the dashboard **Connect** flow) before a fleet can mint a token for it. | | `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | | `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). Transient — retry shortly; if it persists, check GitHub status and the App configuration. | +| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack request signature on `POST /v1/connectors/slack/events` did not verify. Confirm the platform Slack app's signing secret matches the one vaulted by the operator. | +| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack request timestamp is outside the 5-minute drift window — a replay attempt or a skewed clock. | +| `UZ-SLK-020` | 200 | Slack team not installed | The Slack team that sent this event has no connector install; the event is acknowledged (200) and ignored so Slack does not retry. Re-run **Connect Slack** in the dashboard to (re)install. | +| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if it persists, verify the platform Slack app credentials. | +| `UZ-SLK-030` | 502 | Slack answer post failed | The channel bot's answer could not be delivered to Slack (missing `chat:write`, a 429, or a Slack outage). Logged and retried with backoff; the run itself never fails. | ## Approval gate diff --git a/changelog.mdx b/changelog.mdx index 64ca871..474af05 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -22,6 +22,26 @@ export const STAGE_SELF_MANAGED_M66 = "$0.0001"; agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner. + + ## Slack: mention @agentsfleet in a channel, get an answer in the thread + + agentsfleet is now Slack-resident. Connect Slack from the dashboard Integrations page — a browser OAuth round-trip, no token to paste — invite `@agentsfleet` to a channel, and mention it. The first mention materializes a fleet that lives in that channel; it answers in the thread it was mentioned in, and what it learns in one thread it remembers across the channel's other threads. It is reactive and read-only: it speaks only when mentioned, and only in the thread that asked. + + ## What's new + + - **Connect Slack from Integrations.** A Slack row sits next to GitHub: **Connect** redirects to Slack's authorize page and the callback stores the bot token server-side in the workspace vault. The row shows the connected workspace ("Slack connected: {team}") and offers **Reconnect** if the install is revoked. + - **One fleet per channel.** The first `@agentsfleet` mention in a channel creates that channel's resident fleet; later mentions in any thread reuse it. Memory is channel-scoped — tell it a fact in one thread and it recalls it in another. + - **Answers land in-thread.** Replies post to the thread that mentioned the bot — never to the channel top level, never to another channel. + - **Recent thread context.** Each mention re-reads up to 20 recent messages in its thread, so a follow-up mention sees the conversation so far even where the bot wasn't mentioned in between. Best-effort: if Slack throttles the read, the mention still processes without it. + + ## API reference + + - **`POST /v1/workspaces/{workspace_id}/connectors/slack/connect`** (scope `connector:write`) — returns the Slack authorize URL carrying a signed single-use `state`; **`GET /v1/connectors/slack/callback`** finishes the round-trip and vaults the bot token. + - **`GET /v1/workspaces/{workspace_id}/connectors/slack`** (scope `connector:read`) — connector status as `{status, team}`, where `status` is `connected`, `reconnect_required`, or `not_connected`; never a secret. + - **`POST /v1/connectors/slack/events`** — the signed events ingress. Authenticated by Slack's request signature (HMAC over the raw body, 5-minute replay window), not a Bearer token. + - **New error codes:** `UZ-SLK-010` (401, invalid Slack signature), `UZ-SLK-011` (401, stale timestamp), `UZ-SLK-020` (200 — an event from a team with no install is acknowledged and ignored), `UZ-SLK-022` (502, OAuth token exchange failed), `UZ-SLK-030` (502, answer delivery to Slack failed — logged and retried; the run itself never fails). `UZ-CONN-001`/`UZ-CONN-002` now cover the Slack connect flow as well as GitHub. + + ## Bring your own Fleet templates diff --git a/concepts.mdx b/concepts.mdx index 1b14126..a78043d 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -77,9 +77,10 @@ A trigger lands on the event stream. A run opens. The fleet calls tools allow-li - What wakes a fleet. Three sources, all feeding the same reasoning loop: + What wakes a fleet. Four sources, all feeding the same reasoning loop: - **Webhook** — an external system (GitHub, Slack, your monitoring) POSTs to `https://api.agentsfleet.net/v1/webhooks/{fleet_id}/{source}` (one URL per declared trigger source). + - **Slack mention** — with Slack connected, mentioning `@agentsfleet` in a channel wakes that channel's resident fleet, which answers in the thread (see the Jul 02, 2026 changelog entry). - **Cron** — the fleet schedules its own future runs via the `cron_add` tool. - **Steer** — a human invokes `agentsfleet steer "..."` for a manual run. From eb768108acaf3c4fdc33a9e16855b03eb474616f Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 2 Jul 2026 10:42:16 +0530 Subject: [PATCH 2/3] =?UTF-8?q?docs(m106):=20address=20greptile=20review?= =?UTF-8?q?=20on=20#116=20=E2=80=94=20webhook=20example,=20code-gap=20note?= =?UTF-8?q?,=20Slack=20event=20sub-section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - concepts.mdx: drop Slack from the Webhook trigger examples (it has its own dedicated trigger) and say explicitly that a Slack mention does not use the webhook path. - error-codes.mdx: explain the UZ-SLK-021 numbering gap (superseded by the generic UZ-CONN-002 before release); split the four Slack runtime event-handling codes (010/011/020/030) into their own sub-section so operators diagnosing a live channel-bot failure don't scan past them in the OAuth connect & mint table. Co-Authored-By: Claude Fable 5 --- api-reference/error-codes.mdx | 11 ++++++++++- concepts.mdx | 2 +- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 8637e72..112fff8 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -179,6 +179,8 @@ Onboarding a Fleet template (the SKILL.md/TRIGGER.md package behind a Fleet) and ## Integration connect & token mint +Codes here are the externally-observable subset of the server registry; a gap in a numbering sequence is a code that was superseded before release (`UZ-SLK-021` was superseded by the generic `UZ-CONN-002`, so the registry — and this table — skips it). + | Code | HTTP | Title | Common Causes | |---|---|---|---| | `UZ-CONN-001` | 503 | Connector not configured | Connect is unavailable for this provider on this deployment — the platform app credentials (GitHub App slug / Slack app secrets) are unset. An operator must register the provider app and populate the admin vault before workspaces can connect. | @@ -186,10 +188,17 @@ Onboarding a Fleet template (the SKILL.md/TRIGGER.md package behind a Fleet) and | `UZ-CRED-001` | 404 | Integration not connected | No connected integration matches this id for the fleet's workspace. Connect it first (e.g. GitHub via the dashboard **Connect** flow) before a fleet can mint a token for it. | | `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | | `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). Transient — retry shortly; if it persists, check GitHub status and the App configuration. | +| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if it persists, verify the platform Slack app credentials. | + +### Slack event handling + +Runtime codes for the channel bot's inbound mentions and outbound answers — distinct from the OAuth connect and token-mint flow above. + +| Code | HTTP | Title | Common Causes | +|---|---|---|---| | `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack request signature on `POST /v1/connectors/slack/events` did not verify. Confirm the platform Slack app's signing secret matches the one vaulted by the operator. | | `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack request timestamp is outside the 5-minute drift window — a replay attempt or a skewed clock. | | `UZ-SLK-020` | 200 | Slack team not installed | The Slack team that sent this event has no connector install; the event is acknowledged (200) and ignored so Slack does not retry. Re-run **Connect Slack** in the dashboard to (re)install. | -| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if it persists, verify the platform Slack app credentials. | | `UZ-SLK-030` | 502 | Slack answer post failed | The channel bot's answer could not be delivered to Slack (missing `chat:write`, a 429, or a Slack outage). Logged and retried with backoff; the run itself never fails. | ## Approval gate diff --git a/concepts.mdx b/concepts.mdx index a78043d..af6056b 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -79,7 +79,7 @@ A trigger lands on the event stream. A run opens. The fleet calls tools allow-li What wakes a fleet. Four sources, all feeding the same reasoning loop: - - **Webhook** — an external system (GitHub, Slack, your monitoring) POSTs to `https://api.agentsfleet.net/v1/webhooks/{fleet_id}/{source}` (one URL per declared trigger source). + - **Webhook** — an external system (GitHub, your monitoring) POSTs to `https://api.agentsfleet.net/v1/webhooks/{fleet_id}/{source}` (one URL per declared trigger source). A Slack mention does **not** use this path — it has its own trigger below. - **Slack mention** — with Slack connected, mentioning `@agentsfleet` in a channel wakes that channel's resident fleet, which answers in the thread (see the Jul 02, 2026 changelog entry). - **Cron** — the fleet schedules its own future runs via the `cron_add` tool. - **Steer** — a human invokes `agentsfleet steer "..."` for a manual run. From 0f1f0b6deed813066b4caaf7007283c743ed4df7 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 2 Jul 2026 12:42:15 +0530 Subject: [PATCH 3/3] docs: align fleet template API navigation with OpenAPI Amp-Thread-ID: https://ampcode.com/threads/T-019f21a9-2d57-7365-b40e-7ef128491cbb Co-authored-by: Amp --- docs.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs.json b/docs.json index 5898e1a..f1f09de 100644 --- a/docs.json +++ b/docs.json @@ -214,11 +214,12 @@ ] }, { - "group": "Fleet bundles", + "group": "Fleet templates", "pages": [ "GET /v1/fleets/bundles", - "POST /v1/workspaces/{workspace_id}/fleets/bundles/snapshots", - "GET /v1/workspaces/{workspace_id}/fleets/bundles/snapshots/{bundle_id}" + "GET /v1/workspaces/{workspace_id}/fleet-templates", + "POST /v1/admin/fleet-templates", + "POST /v1/workspaces/{workspace_id}/fleet-templates" ] }, {