Synchronize portable ACP agent portraits to Slack app icons

Author: bkrabach

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "acp-slack-adapter"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
@@ -11,6 +11,7 @@ description = "Generic ACP integration with Slack conversations and presentation
 [dependencies]
 anyhow = "1"
 base64 = "0.22"
+image = { version = "0.25", default-features = false, features = ["png"] }
 axum = { version = "0.8.9", features = ["ws", "macros"] }
 axum-server = { version = "0.8.0", features = ["tls-rustls"] }
 clap = { version = "4", features = ["derive"] }
@@ -21,7 +22,7 @@ libc = "0.2"
 pam-client = { version = "0.5.0", default-features = false }
 rand = "0.8"
 rcgen = "0.14"
-reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "multipart"] }
 rusqlite = { version = "0.38", features = ["bundled"] }
 rustls = { version = "0.23", features = ["ring"] }
 rustls-pemfile = "2"

Cargo.toml

@@ -249,3 +249,5 @@ or an already established session ID; tool-scoped questions require a known tool
 Validation uses independent ACP peers and a local Socket Mode service, including
 login, URL opening, typed answers, wrong-user/view rejection, invalid input and
 transcript isolation. Live Slack UI confirmation is a separate check.
+
+Automatic Slack app portraits from compatible agents: [agent images](docs/agent-images.md).

README.md

@@ -0,0 +1,55 @@
+# Keep an agent's Slack image in sync
+
+Upload an image in the connected agent's identity settings. In this connector,
+open **Connection settings → Agent image → Connect image updates**. Supply a
+Slack app configuration access token and its refresh token, generated for the
+workspace under **Your App Configuration Tokens** at https://api.slack.com/apps.
+Use a separate token pair per connector: rotating a shared refresh token in two
+processes would invalidate the other process's copy. These credentials can
+manage your apps; they stay in this connector's private secret store and are
+never sent to the ACP agent or included in configuration exports or UI state.
+
+The connector reads the optional `agent-identity/1` extension over its configured
+ACP connection every two minutes while running. It uploads changed image bytes
+using Slack's documented [`apps.icon.set`](https://docs.slack.dev/reference/methods/apps.icon.set/)
+API. This changes the actual app icon, including DMs and profile surfaces, rather
+than overriding only the appearance of individual messages. No public image
+hosting, `chat:write.customize`, transcript access or model prompt is needed.
+The app configuration token needs `app_configurations:write` and access to this
+app. Manager-app tokens can only change apps they created. Slack remains the
+authority on whether a token may change the selected app.
+
+The bot identity independently verifies the destination app before an upload.
+Icons are deduplicated by checksum; accepted updates and retry deadlines survive
+restarts. A replacement is picked up automatically. Removing a previously synced
+portrait uploads the agent's neutral fallback. An agent without an uploaded
+portrait leaves a manually selected Slack icon alone. Disconnecting image access
+stops sync and leaves Slack's existing icon in place. Slack clients may briefly
+cache old icons after an accepted update.
+
+Failures appear in image status and do not interrupt conversations. Rate limits
+respect `Retry-After`; uncertain responses may safely retry the idempotent icon
+replacement after a delay. Expiring configuration tokens rotate using
+[`tooling.tokens.rotate`](https://docs.slack.dev/reference/methods/tooling.tokens.rotate/)
+when a refresh token is configured. A lost/revoked token needs reconnecting.
+
+## Generic ACP compatibility
+
+Portable identity is optional, **not part of base ACP**. Any ACP implementation
+can implement the [documented extension](https://github.com/microsoft/amplifier-constellation-instance/blob/main/docs/agent-identity.md).
+The connector only calls the exact advertised method and accepts bounded,
+checksum-verified PNG bytes. It does not read the agent's installation files,
+use its management token, or fetch an agent-provided image URL. Agents without
+this extension keep their normal Slack icon and ordinary ACP behavior.
+
+## Automation
+
+- `GET /api/v1/identity`: synchronization status (`observe`).
+- `POST /api/v1/identity` with `{}`: sync now (`admin`), respecting retry deadlines.
+- `PUT /api/v1/identity/credential` with `{ "token": "...", "refresh_token": "..." }`:
+  save private configuration access (`admin`). Optional `expires_at` is Unix seconds.
+- `DELETE /api/v1/identity/credential`: stop synchronization and remove local access.
+
+The UI exposes `identity.open`, `identity.credentials`, `identity.sync` and
+`identity.disconnect` through `slackConnector.act`. Its view/modal state uses the
+existing authenticated view API. Credential input values are excluded from it.

docs/agent-images.md

@@ -380,6 +380,28 @@ pub async fn check(c: &Config, home: &Path) -> Result<Value> {
         Ok(json!({"ok":true,"protocol_version":1,"agent_info":init["agentInfo"],"load_session":init["agentCapabilities"]["loadSession"]==true,"authentication":crate::acp_auth::authentication(&init),"note":"ACP handshake and session creation succeeded. No prompt or Slack message was sent."}))
     }).await.context("ACP connection check timed out")?
 }
+/// Optional presentation extension. No session, model prompt, or remote URL fetch.
+pub async fn identity(c: &Config, home: &Path) -> Result<Option<Value>> {
+    tokio::time::timeout(Duration::from_secs(30), async {
+        let mut config = c.clone();
+        config.acp.client = Default::default();
+        let (mut client, init) = Client::connect(&config, home).await?;
+        let capability = &init["_meta"]["com.microsoft.amplifier.identity"];
+        if capability["schema"] != "agent-identity/1"
+            || capability["method"] != "_amplifier/identity/get"
+        {
+            return Ok(None);
+        }
+        Ok(Some(
+            client
+                .peer
+                .request("_amplifier/identity/get", json!({}))
+                .await?,
+        ))
+    })
+    .await
+    .context("Agent identity check timed out")?
+}
 pub async fn decide(c: Config, home: PathBuf, input: Value) -> Result<Decision> {
     let timeout = c.acp.timeout_seconds;
     tokio::time::timeout(Duration::from_secs(timeout), turn(&c, &home, &input))