The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
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.mdindex 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, otherwisethe 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.tsindex 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.tsindex 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.tsindex 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)) };}