Skip to content

The open-source app everyone uses to manage agents at work

fix(slack): upload agent avatars directly during Cloud setup (#15566)

Dottaf47614046d51
diff --git a/doc/connections/SLACK-AUTOMATIC-SETUP.md b/doc/connections/SLACK-AUTOMATIC-SETUP.md
index e50a2fb67b..67b8cf6672 100644
--- a/doc/connections/SLACK-AUTOMATIC-SETUP.md
+++ b/doc/connections/SLACK-AUTOMATIC-SETUP.md
@@ -120,11 +120,11 @@ the browser cannot supply a manifest, scopes, or callback destination.
- Webhook URLs use `PAPERCLIP_CHAT_WEBHOOK_PUBLIC_URL` when configured, otherwise
the canonical board origin. They end in `/api/chat-webhooks/<publicId>/slack`.
A separate webhook ingress must route signed webhook requests to the instance.
-- Avatar upload uses a server-derived public preset PNG URL on the canonical
- board origin (`/api/agent-avatars/cap-v1/<palette>/rest.png?size=512&scale=1&background=paperclip-dark`).
- Slack must be able to fetch this route without login. It serves preset artwork
- without company or agent lookup. A failed fetch leaves installation usable and
- offers manual upload; callers cannot choose an arbitrary image URL.
+- Avatar upload renders the assigned agent's preset PNG on the server and sends
+ its bytes through `apps.icon.set` as multipart form data. Slack does not need to
+ fetch an image from the tenant's authenticated board origin. The image is
+ 512 × 512 with the Paperclip dark background. The temporary configuration
+ token stays in the Authorization header and is discarded after setup.
- Cloud resolves its current canonical origin from its claimed runtime identity.
Self-hosted deployments use the configured authentication public base URL
(`PAPERCLIP_AUTH_PUBLIC_BASE_URL` or `PAPERCLIP_PUBLIC_URL`).
diff --git a/server/src/__tests__/chat-channels.integration.test.ts b/server/src/__tests__/chat-channels.integration.test.ts
index c76efbb685..4d81ac5e1c 100644
--- a/server/src/__tests__/chat-channels.integration.test.ts
+++ b/server/src/__tests__/chat-channels.integration.test.ts
@@ -4059,14 +4059,16 @@ describeEmbeddedPostgres("chat channel control-plane integration", () => {
return fallback(input, init);
});
const sdk = new FakeChatSdkRuntime();
- const { service } = createService(sdk, provider, overrides);
+ const avatarBytes = Buffer.from("synthetic-png-bytes");
+ const renderAvatar = vi.fn(async () => avatarBytes);
+ const { service } = createService(sdk, provider, { renderSlackAvatar: renderAvatar, ...overrides });
const endpoint = await service.create(company.companyId, { provider: "slack", assignedAgentId: company.assignedAgentId }, actor.userId);
await service.update(endpoint.id, { slackApp: appDetails }, actor.userId);
const app = routesApp(db, company.companyId, service);
const createInput = { requestId: randomUUID(), credentials: { configurationToken: configToken } };
const create = (input = createInput) => service.slackRegistration.create(endpoint.id, actor, input);
const install = async () => new URL((await service.slackRegistration.install(endpoint.id, actor)).authorizationUrl).searchParams.get("state")!;
- return { ...company, endpoint, service, sdk, app, state, provider, create, install, createInput, token, appId, botId, installerId };
+ return { ...company, endpoint, service, sdk, app, state, provider, create, install, createInput, token, appId, botId, installerId, avatarBytes, renderAvatar };
}
function setupEvent(f: Awaited<ReturnType<typeof fixture>>, patch: Record<string, unknown> = {}, url = f.endpoint.setup.webhookUrl!, secret = signingSecret, timestamp?: string) {
return signedSlackWebhookRequest({ url, contentType: "application/json", signingSecret: secret, ...(timestamp ? { timestamp } : {}),
@@ -4136,7 +4138,7 @@ describeEmbeddedPostgres("chat channel control-plane integration", () => {
for (const canary of [configToken, signingSecret, clientSecret, f.token]) expect(publicState).not.toContain(canary);
await request(f.app).patch(`/api/chat-endpoints/${f.endpoint.id}`).send({ slackApp: appDetails }).expect(409);
});
- it("uploads the assigned agent's public avatar only after the app credentials are durable", async () => {
+ it("uploads avatar bytes without fetching a tenant-session-protected URL, after app credentials are durable", async () => {
const f = await fixture();
await db.update(agents).set({ appearance: { schemaVersion: 1, characterVersion: "cap-v1", paletteId: "cherry-pop" } }).where(eq(agents.id, f.assignedAgentId));
f.state.beforeIcon = async () => {
@@ -4148,10 +4150,40 @@ describeEmbeddedPostgres("chat channel control-plane integration", () => {
await f.create();
const [, init] = f.provider.mock.calls.find(([url]) => String(url).endsWith("apps.icon.set"))!;
expect(init).toMatchObject({ method: "POST", redirect: "error", headers: { authorization: `Bearer ${configToken}` } });
- const fields = new URLSearchParams(String(init!.body));
- expect(Object.fromEntries(fields)).toEqual({ app_id: f.appId, url: "https://paperclip.example/api/agent-avatars/cap-v1/cherry-pop/rest.png?size=512&scale=1&background=paperclip-dark" });
+ expect(f.renderAvatar).toHaveBeenCalledWith({ appearance: { schemaVersion: 1, characterVersion: "cap-v1", paletteId: "cherry-pop" },
+ size: 512, scale: 1, pose: "rest", muted: false, background: "paperclip-dark" });
+ expect(init!.body).toBeInstanceOf(FormData);
+ const fields = init!.body as FormData;
+ expect(fields.get("app_id")).toBe(f.appId);
+ expect(fields.has("url")).toBe(false);
+ expect(fields.has("token")).toBe(false);
+ expect(init!.headers).not.toHaveProperty("content-type"); // fetch sets the multipart boundary.
+ const file = fields.get("file") as File;
+ expect(file.type).toBe("image/png");
+ expect(file.name).toBe("agent-avatar.png");
+ expect(Buffer.from(await file.arrayBuffer())).toEqual(f.avatarBytes);
+ expect(f.provider.mock.calls.every(([url]) => !String(url).includes("/agent-avatars/"))).toBe(true);
expect((await request(f.app).get(`/api/chat-endpoints/${f.endpoint.id}`).expect(200)).body.setup.slackAvatar.status).toBe("uploaded");
});
+ it("uploads a real 512-pixel PNG from the production renderer", async () => {
+ const f = await fixture({ renderSlackAvatar: undefined });
+ await f.create();
+ const [, init] = f.provider.mock.calls.find(([url]) => String(url).endsWith("apps.icon.set"))!;
+ const file = (init!.body as FormData).get("file") as File;
+ const png = Buffer.from(await file.arrayBuffer());
+ expect(png.subarray(0, 8)).toEqual(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+ expect(png.readUInt32BE(16)).toBe(512);
+ expect(png.readUInt32BE(20)).toBe(512);
+ expect((await f.service.get(f.endpoint.id)).setup.slackAvatar?.status).toBe("uploaded");
+ });
+ it("keeps the saved app installable after local avatar rendering fails", async () => {
+ const f = await fixture({ renderSlackAvatar: async () => { throw new Error("render failed"); } });
+ await f.create();
+ expect((await f.service.get(f.endpoint.id)).setup.slackAvatar).toEqual({ status: "failed", errorCode: "slack_avatar_upload_failed" });
+ expect(f.provider.mock.calls.some(([url]) => String(url).endsWith("apps.icon.set"))).toBe(false);
+ await expect(f.install()).resolves.toMatch(/^slack-install\./);
+ expect(f.provider.mock.calls.filter(([url]) => String(url).endsWith("apps.manifest.create"))).toHaveLength(1);
+ });
it.each(["failIcon", "timeoutIcon"] as const)("keeps installation usable after %s without leaking provider echoes or creating another app", async failure => {
const f = await fixture();
f.state[failure] = true;
diff --git a/server/src/services/chat-channels.ts b/server/src/services/chat-channels.ts
index 04952ebb61..5300692f9c 100644
--- a/server/src/services/chat-channels.ts
+++ b/server/src/services/chat-channels.ts
@@ -1,4 +1,5 @@
import { chatCredentialMutationLease, CREDENTIAL_MUTATION_LEASE_TTL_MS, type CredentialMutationLeaseGuard } from "./chat-credential-mutation-lease.js";
+import type { AgentAvatarRequest } from "./agent-avatars.js";
import { slackChatRegistrationService, slackRegistrationProjection } from "./chat-slack-registration.js";
import { chatSlackRegistrations } from "@paperclipai/db";
import { SLACK_CHAT_BOT_SCOPES } from "@paperclipai/shared";
@@ -1525,6 +1526,7 @@ export interface ChatChannelServiceOptions {
actionId: string;
claimId: string;
}) => Promise<void>;
+ renderSlackAvatar?: (request: AgentAvatarRequest) => Promise<Buffer>;
storage?: StorageService;
}
@@ -38130,7 +38132,7 @@ export function chatChannelService(db: Db, options: ChatChannelServiceOptions) {
}
const slackRegistration = slackChatRegistrationService(db, {
- publicOrigin: getPublicBaseUrl, webhookOrigin: getWebhookPublicBaseUrl, fetch: fetchImpl,
+ publicOrigin: getPublicBaseUrl, webhookOrigin: getWebhookPublicBaseUrl, fetch: fetchImpl, renderAvatar: options.renderSlackAvatar,
withLock: async (endpointId, work) => {
const record = await endpointRecord(endpointId);
if (!record) throw notFound("Chat endpoint not found");
@@ -38400,6 +38402,7 @@ export function chatChannelService(db: Db, options: ChatChannelServiceOptions) {
// Stop every provider runtime before releasing leader rows. This gives a
// standby an immediate takeover path without overlapping Gateway sockets.
await runtime.shutdown();
+ await slackRegistration.close();
await Promise.all(
ownedDiscordGateways.map((ownership) =>
releaseDiscordGatewayLeaseRow(ownership),
diff --git a/server/src/services/chat-slack-registration.ts b/server/src/services/chat-slack-registration.ts
index 59c96d07da..212bc4054a 100644
--- a/server/src/services/chat-slack-registration.ts
+++ b/server/src/services/chat-slack-registration.ts
@@ -1,8 +1,10 @@
+import { createAgentAvatarPool } from "./agent-avatar-pool.js";
+import type { AgentAvatarRequest } from "./agent-avatars.js";
import { removeSlackRegistration } from "./chat-slack-registration-cleanup.js";
import { createHash, randomBytes } from "node:crypto";
import { and, eq, gt, inArray, like, sql } from "drizzle-orm";
import { agents, chatEndpoints, chatSlackRegistrations, companies, toolConnections, toolOauthStates, type Db } from "@paperclipai/db";
-import { agentAvatarUrl, resolveAgentAppearance, buildSlackAppManifest, slackAppConfigurationSchema, slackRegistrationErrorMessage, type SlackRegistrationInput, type SlackRegistrationState, type SlackAvatarState, type SlackAccountState } from "@paperclipai/shared";
+import { resolveAgentAppearance, buildSlackAppManifest, slackAppConfigurationSchema, slackRegistrationErrorMessage, type SlackRegistrationInput, type SlackRegistrationState, type SlackAvatarState, type SlackAccountState } from "@paperclipai/shared";
import { badRequest, conflict, forbidden, notFound, unprocessable } from "../errors.js";
import { accessService } from "./access.js";
import { logActivity } from "./activity-log.js";
@@ -39,6 +41,7 @@ export function slackChatRegistrationService(db: Db, options: {
publicOrigin: () => string | null;
webhookOrigin: () => string | null;
fetch?: typeof fetch;
+ renderAvatar?: (request: AgentAvatarRequest) => Promise<Buffer>;
withLock: <T>(endpointId: string, work: (lease: CredentialMutationLeaseGuard) => Promise<T>) => Promise<T>;
runtimeSigningSecret: (endpointId: string) => Promise<string>;
runtimeBotToken: (endpointId: string) => Promise<string>;
@@ -48,6 +51,7 @@ export function slackChatRegistrationService(db: Db, options: {
}) {
const fetchImpl = options.fetch ?? fetch;
const vault = secretService(db);
+ let avatarPool: ReturnType<typeof createAgentAvatarPool> | undefined;
function origin(value: string | null) {
if (!value) throw badRequest("Configure a public HTTPS URL before creating a Slack app");
const url = new URL(value);
@@ -81,11 +85,11 @@ export function slackChatRegistrationService(db: Db, options: {
action: `chat_slack.${action}`, entityType: "chat_endpoint", entityId: row.endpointId,
details: { endpointId: row.endpointId, appId: row.appId, ...(code ? { code } : {}) } });
}
- async function api(method: string, fields: Record<string, string>, bearer?: string) {
+ async function api(method: string, fields: Record<string, string> | FormData, bearer?: string) {
const response = await fetchImpl(`https://slack.com/api/${method}`, {
method: "POST", redirect: "error", signal: AbortSignal.timeout(timeoutMs),
- headers: { "content-type": "application/x-www-form-urlencoded", ...(bearer ? { authorization: `Bearer ${bearer}` } : {}) },
- body: new URLSearchParams(fields),
+ headers: { ...(fields instanceof FormData ? {} : { "content-type": "application/x-www-form-urlencoded" }), ...(bearer ? { authorization: `Bearer ${bearer}` } : {}) },
+ body: fields instanceof FormData ? fields : new URLSearchParams(fields),
});
const result = object(await response.json());
if (!response.ok || result.ok !== true) {
@@ -211,9 +215,17 @@ export function slackChatRegistrationService(db: Db, options: {
try {
await endpoint(endpointId, actor);
await lease.assertOwned();
- // Public preset artwork from our configured origin; never accept a caller's URL.
- const imageUrl = new URL(agentAvatarUrl(resolveAgentAppearance(current.agentAppearance, current.endpoint.assignedAgentId), 512, 1, "rest", false, "paperclip-dark"), origin(options.publicOrigin())).href;
- await api("apps.icon.set", { app_id: createdAppId, url: imageUrl }, input.credentials.configurationToken);
+ // Cloud ingress requires a tenant session. Send the preset PNG bytes so
+ // Slack does not need to fetch an authenticated Paperclip URL.
+ const render = options.renderAvatar ?? (avatarPool ??= createAgentAvatarPool()).render;
+ const png = await render({ appearance: resolveAgentAppearance(current.agentAppearance, current.endpoint.assignedAgentId),
+ size: 512, scale: 1, pose: "rest", muted: false, background: "paperclip-dark" });
+ await endpoint(endpointId, actor);
+ await lease.assertOwned();
+ const upload = new FormData();
+ upload.set("app_id", createdAppId);
+ upload.set("file", new Blob([new Uint8Array(png)], { type: "image/png" }), "agent-avatar.png");
+ await api("apps.icon.set", upload, input.credentials.configurationToken);
avatar = { status: "uploaded", uploadedAt: new Date().toISOString() };
} catch {
// Provider echoes (including tokens) never become saved state or activity.
@@ -492,5 +504,6 @@ export function slackChatRegistrationService(db: Db, options: {
return `/${encodeURIComponent(row.prefix)}/apps/chat/connect?provider=slack&resume=${encodeURIComponent(endpointId)}`;
}
return { create, install, pending, expiredReturn, complete, cleanup, returnPath, registration, notifyVerified, processPendingVerificationMessages,
+ close: async () => { await avatarPool?.close(); },
resume: (endpointId: string, actor: SlackSetupActor) => options.withLock(endpointId, lease => resumeLocked(endpointId, actor, lease)) };
}