Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Use Slack mirror context and guide workspace app setup (#1206)

Regan Bellf97652c109e0
diff --git a/README.md b/README.md
index 8daea7812..6ce5f1f6d 100644
--- a/README.md
+++ b/README.md
@@ -272,3 +272,18 @@ and app before passing it to the existing Slack runtime and acknowledgment
machinery. There is no shared queue: unavailable core instances return failures,
and the hosting service must relay those failures to Slack. The service must
process lifecycle events and ignore revocations older than the installation.
+
+Managed deployments also support an administrator-provided Slack app through the same
+Slack settings card. Saving its validated bot and Socket Mode tokens replaces the
+managed runtime and rejects subsequent managed installation callbacks. To return to
+the managed app, disconnect the administrator-provided app in QM, then explicitly
+choose **Add to Slack**. Disconnecting alone does not permit old managed callbacks to
+restore an installation.
+
+Use the same Slack workspace when replacing the managed app, so existing conversations
+and memberships remain associated with that workspace. Invite the new bot to the
+channels it should serve; Slack does not transfer the old bot's memberships. Once
+replacement is verified, remove the old managed app from Slack to avoid two visible
+QM identities. QM rejects deliveries for the old installation as soon as the new
+credentials are saved. The replacement uses Socket Mode even if the deployment's
+environment previously selected HTTP events.
diff --git a/plugins/admin/public/index.html b/plugins/admin/public/index.html
index f7d81c657..f9fa1e825 100644
--- a/plugins/admin/public/index.html
+++ b/plugins/admin/public/index.html
@@ -5024,7 +5024,7 @@
/></label>
</div>
<div class="foot">
- <button class="primary" id="onboarding-model-save">Validate and save</button
+ <button class="primary" id="onboarding-model-save">Validate and connect</button
><button class="danger" id="onboarding-model-delete">Disable this provider</button
><span class="status" id="st-onboarding-model"></span>
</div>
@@ -6138,17 +6138,50 @@
</p>
</div>
<div class="body">
- <p>
- <a
- id="slack-installation-create"
- href="https://api.slack.com/apps?new_app=1"
- target="_blank"
- rel="noopener noreferrer"
- >Create Slack app from manifest ↗</a
- >
- </p>
<button class="primary hidden" id="slack-installation-start">Add to Slack</button>
<p class="hint" id="slack-installation-state">Not configured.</p>
+ <details id="slack-own-app-guide">
+ <summary>Set up your own Slack app</summary>
+ <p>
+ Use a workspace-owned app with your bot's name. You'll need permission to install apps in Slack.
+ Slack still applies rate limits; this does not provide unlimited history.
+ </p>
+ <ol>
+ <li>
+ <a
+ id="slack-installation-create"
+ href="https://api.slack.com/apps?new_app=1"
+ target="_blank"
+ rel="noopener noreferrer"
+ >Create your preconfigured Slack app ↗</a
+ >. Choose your company workspace, review the permissions, and click <strong>Create</strong>. The
+ manifest sets up the bot, message events, buttons, and Socket Mode for you.
+ </li>
+ <li>
+ In <strong>OAuth &amp; Permissions</strong>, click <strong>Install to Workspace</strong> and
+ approve access. Copy the <strong>Bot User OAuth Token</strong> starting with <code>xoxb-</code>.
+ </li>
+ <li>
+ In <strong>Basic Information → App-Level Tokens</strong>, click
+ <strong>Generate Token and Scopes</strong>. Name it <strong>QM connection</strong>, add
+ <code>connections:write</code>, and generate it. Copy the token starting with <code>xapp-</code>.
+ </li>
+ <li>
+ Paste both tokens below and click <strong>Validate and connect</strong>. Keep this page open while
+ you work in Slack. Tokens must come from the same app.
+ </li>
+ <li>
+ Invite your new bot to a channel, mention it, then send it a DM to check both surfaces. It only
+ sees conversations it can access; older history may be incomplete.
+ </li>
+ </ol>
+ <p class="hint">
+ Replacing a connected app changes the Slack bot identity. Invite the new bot to your channels and
+ start a new DM with it. The old app stays installed in Slack until a workspace admin removes it. To
+ switch back to the hosted app, remove this connection first, then choose Add to Slack.
+ </p>
+ <button type="button" id="slack-enter-tokens">I have both tokens</button>
+ </details>
<div class="hidden" id="slack-token-editor">
<label style="display: block; margin-bottom: 8px"
>Bot User OAuth Token
@@ -6176,7 +6209,7 @@
</div>
<div class="foot">
<button type="button" id="slack-rotate">Rotate tokens…</button
- ><button class="primary hidden" id="slack-installation-save">Validate and save</button
+ ><button class="primary hidden" id="slack-installation-save">Validate and connect</button
><button class="danger" id="slack-installation-delete">Remove</button
><span class="status" id="st-slack-installation"></span>
</div>
@@ -7131,6 +7164,7 @@
const path = scopeInPath ? API_BASE + "/history/scopes/" + scopeSegment : API_BASE + "/history";
return q ? path + "?" + q : path;
}
+ if (st.view === "connectors" && st.setup === "slack") p.set("setup", "slack");
if (st.scope && SCOPED.has(st.view)) p.set("scope", st.scope);
if (st.view === "errors" && st.page > 1) p.set("page", st.page);
if (st.principal) p.set("principal", st.principal);
@@ -7173,7 +7207,7 @@
if (segs[1] === "s") pathSession = decodePathSegment(segs[2] ?? "");
else if (segs[1] === "scopes") pathScope = decodePathSegment(segs[2] ?? "");
}
- const raw = p.get("view") || fromPath;
+ const raw = p.get("setup") === "slack" ? "connectors" : p.get("view") || fromPath;
const v = raw === "skill-packs" ? "skills" : raw;
const session = pathSession || p.get("session") || null;
@@ -7188,6 +7222,7 @@
else if (session) resolvedView = "history";
return {
view: resolvedView,
+ setup: p.get("setup"),
scope:
pathScope ||
p.get("scope") ||
@@ -10234,8 +10269,16 @@
return;
}
$("slack-installation-start").classList.toggle("hidden", !r.data.installAvailable);
- $("slack-installation-create").classList.toggle("hidden", !!r.data.installAvailable);
- $("slack-rotate").classList.toggle("hidden", !!r.data.installAvailable);
+ $("slack-installation-start").disabled = r.data.configured && r.data.source === "admin";
+ $("slack-installation-start").title =
+ r.data.configured && r.data.source === "admin"
+ ? "Remove your current connection before switching to the hosted app."
+ : "";
+ $("slack-rotate").textContent = r.data.configured ? "Replace connection…" : "Set up your own app…";
+ if (new URLSearchParams(location.search).get("setup") === "slack") {
+ $("slack-own-app-guide").open = true;
+ $("card-slack-installation").scrollIntoView({ block: "start" });
+ }
if (r.data.createUrl) $("slack-installation-create").href = r.data.createUrl;
$("slack-installation-state").textContent =
r.data.source === "environment"
@@ -10283,9 +10326,17 @@
$("slack-token-editor").classList.add("hidden");
$("slack-installation-save").classList.add("hidden");
await loadSlackInstallation();
- setStatus("st-slack-installation", "Saved. Slack is activating.", "ok");
+ setStatus(
+ "st-slack-installation",
+ "Tokens verified and saved. Allow a few seconds, then test a mention and DM in Slack.",
+ "ok",
+ );
};
$("slack-rotate").onclick = () => {
+ $("slack-own-app-guide").open = true;
+ $("slack-own-app-guide").scrollIntoView({ behavior: "smooth", block: "start" });
+ };
+ $("slack-enter-tokens").onclick = () => {
$("slack-token-editor").classList.remove("hidden");
$("slack-installation-save").classList.remove("hidden");
$("slack-bot-token").focus();
diff --git a/plugins/admin/src/index.ts b/plugins/admin/src/index.ts
index 0f563d30e..e5c1df549 100644
--- a/plugins/admin/src/index.ts
+++ b/plugins/admin/src/index.ts
@@ -338,7 +338,7 @@ const server = createServer((req, res) => {
async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
res.setHeader("strict-transport-security", "max-age=63072000; includeSubDomains");
- res.setHeader("referrer-policy", "no-referrer");
+ res.setHeader("referrer-policy", process.env.QM_SLACK_SERVICE_URL ? "strict-origin" : "no-referrer");
res.setHeader("x-content-type-options", "nosniff");
res.setHeader("x-frame-options", "DENY");
res.setHeader("content-security-policy", ADMIN_CSP);
diff --git a/plugins/admin/test/default-view.test.ts b/plugins/admin/test/default-view.test.ts
index c715193a2..1c7fc9c1b 100644
--- a/plugins/admin/test/default-view.test.ts
+++ b/plugins/admin/test/default-view.test.ts
@@ -101,7 +101,7 @@ test("temporary onboarding covers model credentials, Slack, and OAuth setup", ()
test("admin shell addresses views by path, not a ?view= query param", () => {
assert.match(html, /const path = API_BASE \+ "\/" \+ encodeURIComponent\(st\.view \|\| DEFAULT_VIEW\);/);
assert.doesNotMatch(html, /p\.set\("view", st\.view\)/);
- assert.match(html, /const raw = p\.get\("view"\) \|\| fromPath;/);
+ assert.match(html, /const raw = p\.get\("setup"\) === "slack" \? "connectors" : p\.get\("view"\) \|\| fromPath;/);
assert.doesNotMatch(html, /st\.view !== "governance"/);
});
diff --git a/plugins/admin/test/history-urls.test.ts b/plugins/admin/test/history-urls.test.ts
index 5cfd6ea38..f6de940bb 100644
--- a/plugins/admin/test/history-urls.test.ts
+++ b/plugins/admin/test/history-urls.test.ts
@@ -28,6 +28,7 @@ function routerAt(pathname: string, search = "", base = "/admin") {
base,
new Set(["history", "files", "memory", "live", "audit", "errors", "skills", "crons", "deployments"]),
[
+ "connectors",
"history",
"files",
"memory",
@@ -50,6 +51,7 @@ function routerAt(pathname: string, search = "", base = "/admin") {
stateToUrl: (st: Record<string, unknown>) => string;
urlToState: () => {
view: string;
+ setup: string | null;
scope: string;
session: string | null;
historyKind: string;
@@ -181,3 +183,16 @@ test("Errors pagination round-trips arbitrary pages without losing scope", () =>
`/admin/errors?scope=${SCOPE_ENC}&page=37`,
);
});
+
+test("Slack setup links select connectors and preserve the guide through canonical routing", () => {
+ for (const pathname of ["/admin", "/admin/", "/admin/connectors"]) {
+ const { stateToUrl, urlToState } = routerAt(pathname, "?setup=slack");
+ const state = urlToState();
+ assert.equal(state.view, "connectors");
+ assert.equal(state.setup, "slack");
+ assert.equal(stateToUrl(state), "/admin/connectors?setup=slack");
+ }
+ const { stateToUrl } = routerAt("/admin/connectors", "?setup=slack");
+ assert.equal(stateToUrl({ view: "connectors" }), "/admin/connectors");
+ assert.equal(stateToUrl({ view: "files", setup: "slack" }), "/admin/files");
+});
diff --git a/plugins/admin/test/whoami.test.ts b/plugins/admin/test/whoami.test.ts
index db7762a25..067c70db7 100644
--- a/plugins/admin/test/whoami.test.ts
+++ b/plugins/admin/test/whoami.test.ts
@@ -57,6 +57,19 @@ test("admin HTML ships a hash-only script policy and transport/browser isolation
assert.equal(r.headers.get("x-frame-options"), "DENY");
});
+test("managed Slack form navigation retains origin without disclosing the admin path", async () => {
+ const previous = process.env.QM_SLACK_SERVICE_URL;
+ process.env.QM_SLACK_SERVICE_URL = "https://slack.example.test";
+ try {
+ const r = await api("/connectors?private=hidden");
+ assert.equal(r.status, 200);
+ assert.equal(r.headers.get("referrer-policy"), "strict-origin");
+ } finally {
+ if (previous === undefined) delete process.env.QM_SLACK_SERVICE_URL;
+ else process.env.QM_SLACK_SERVICE_URL = previous;
+ }
+});
+
test("/api/whoami with cookie admin=U-admin → 200 with the core's admin status", async () => {
const r = await api("/api/whoami", "admin=U-admin");
assert.equal(r.status, 200);
diff --git a/src/api/routes/admin/slack-installation.ts b/src/api/routes/admin/slack-installation.ts
index 6271eb704..fa5fae318 100644
--- a/src/api/routes/admin/slack-installation.ts
+++ b/src/api/routes/admin/slack-installation.ts
@@ -38,7 +38,13 @@ export async function getSlackInstallation(ctx: ApiCtx): Promise<void> {
const createUrl = slackBotManifestCreationUrl(branding.selfLabel);
if (ctx.deps.managedSlack) {
const status = await ctx.deps.slackInstallation.status();
- return sendJson(ctx.res, 200, { ...status, source: "service", installAvailable: true });
+ const installation = await ctx.deps.slackInstallation.get();
+ return sendJson(ctx.res, 200, {
+ ...status,
+ source: installation?.appToken ? "admin" : "service",
+ installAvailable: true,
+ createUrl,
+ });
}
const stored = await ctx.deps.slackInstallation.status();
if (stored.managed) return sendJson(ctx.res, 200, { ...stored, source: "admin", createUrl });
@@ -58,7 +64,6 @@ export async function putSlackInstallation(ctx: ApiCtx): Promise<void> {
const actor = await authorizeAdmin(ctx, scope);
if (!actor) return;
if (!ctx.deps.slackInstallation) return sendJson(ctx.res, 404, { error: "not_configured" });
- if (ctx.deps.managedSlack) return sendJson(ctx.res, 409, { error: "use_managed_installation" });
const body = ctx.body as { botToken?: unknown; appToken?: unknown };
const botToken = typeof body.botToken === "string" ? body.botToken.trim() : "";
const appToken = typeof body.appToken === "string" ? body.appToken.trim() : "";
diff --git a/src/api/slack-core-client.ts b/src/api/slack-core-client.ts
index 5f827832e..c2ca5a9d6 100644
--- a/src/api/slack-core-client.ts
+++ b/src/api/slack-core-client.ts
@@ -16,7 +16,7 @@ import type {
TurnResult,
} from "../types.ts";
import { scopeId } from "../types.ts";
-import type { IngestEvent } from "../surface-cache/surface-cache.ts";
+import type { CachedMessage, ReadMessagesOpts, SurfaceCache, IngestEvent } from "../surface-cache/surface-cache.ts";
import type { AckEmojiPickStore } from "../surface-cache/ack-emoji-pick-store.ts";
import type { OrgBranding, ScopedConfigStore } from "../resolution/config-store.ts";
import type { BlobTransferStore } from "../persistence/blob-transfer.ts";
@@ -98,6 +98,8 @@ export interface SlackCoreClient {
stageBlob(bytes: Uint8Array): Promise<{ blobId: string; sizeBytes: number }>;
readBlob(blobId: string): Promise<Buffer>;
readFileArtifact(artifactId: string, viewerId: string): Promise<Buffer>;
+ rememberSurfaceHistory?(events: IngestEvent[]): Promise<void>;
+ readSurfaceMessages?(container: string, opts?: ReadMessagesOpts): Promise<CachedMessage[]>;
ingestSurfaceEvents(events: IngestEvent[], self?: { name?: string; mentionId?: string }): Promise<void>;
submitTurn(body: Omit<TurnRequest, "surface">): Promise<TurnResult>;
waitRun(runId: string, hooks?: SlackRunHooks): Promise<TurnResult | null>;
@@ -167,6 +169,7 @@ export interface SlackCoreClientDeps {
brandingDefault?: OrgBranding;
leaderLease?: LeaderLease;
stagedEnvelopes?: DurableMap<StagedEnvelope>;
+ surfaceCache?: SurfaceCache;
inboxEvent?(event: ConversationEvent): Promise<void>;
}
@@ -282,6 +285,14 @@ export function createSlackCoreClient(deps: SlackCoreClientDeps): SlackCoreClien
return buffer(opened.stream);
},
+ async rememberSurfaceHistory(events) {
+ await deps.surfaceCache?.ingest(events);
+ },
+
+ async readSurfaceMessages(container, opts) {
+ return deps.app.readSurfaceMessages(container, { ...opts, noFallback: true });
+ },
+
async ingestSurfaceEvents(events, self) {
if (!events.length) return;
await deps.app.ingestSurfaceEvents(events, "slack", self);
diff --git a/src/core/orchestrator/surface-tools.ts b/src/core/orchestrator/surface-tools.ts
index 27d13ddc3..f15d20884 100644
--- a/src/core/orchestrator/surface-tools.ts
+++ b/src/core/orchestrator/surface-tools.ts
@@ -182,7 +182,8 @@ export function createSurfaceToolDeps(ctx: SurfaceToolsContext): SurfaceToolDeps
coverageChecked = true;
const container = currentDestination.target ?? conversation.channelRef ?? conversation.threadRef;
if (!deps.surfaceCache || !container) return coverageSince;
- const st = await deps.surfaceCache.containerState(container).catch(() => null);
+ const cacheContainer = currentDestination.type === "slack" ? container.split(":")[0]! : container;
+ const st = await deps.surfaceCache.containerState(cacheContainer).catch(() => null);
coverageSince = st?.oldestTs ? isoFromTs(st.oldestTs) || undefined : undefined;
return coverageSince;
};
@@ -297,7 +298,7 @@ export function createSurfaceToolDeps(ctx: SurfaceToolsContext): SurfaceToolDeps
});
if (!result) return { ok: false, message: "the surface didn't answer in time" };
if (result.note && !result.messages?.length) return { ok: false, message: result.note };
- return { ok: true, messages: result.messages };
+ return { ok: true, messages: result.messages, ...(result.note ? { message: result.note } : {}) };
},
whatsNew: async (opts?: { since?: string }) => {
if (!deps.surfaceContext) return { ok: false, message: "the surface can't be read from this turn" };
@@ -332,6 +333,7 @@ export function createSurfaceToolDeps(ctx: SurfaceToolsContext): SurfaceToolDeps
ok: true,
hereNew,
activeSubConversations: otherRoots.size,
+ ...(result.note ? { message: result.note } : {}),
...(latest ? { latest } : {}),
...(coverage ? { coverageSince: coverage } : {}),
};
@@ -383,6 +385,24 @@ export function createSurfaceToolDeps(ctx: SurfaceToolsContext): SurfaceToolDeps
return withCoverage({ ok: true, hits: shapeHits(result.messages ?? [], true), source: "slack" });
}
const container = dest.target ?? conversation.channelRef ?? conversation.threadRef;
+ if (deps.surfaceCache && dest.type === "slack" && container) {
+ const channel = container.split(":")[0]!;
+ const hits = await deps.surfaceCache.search(q, { container: channel, limit });
+ return withCoverage({
+ ok: true,
+ hits: hits.map((hit) => ({
+ ref: hit.ts,
+ ...(hit.authorName ? { author: hit.authorName } : {}),
+ when: isoFromTs(hit.ts),
+ snippet: hit.text.slice(0, 200),
+ })),
+ source: "cache",
+ message: "Search covers stored Slack events only; older or missed messages may be absent.",
+ });
+ }
+ if (opts?.source === "mirror" && !deps.surfaceSearch) {
+ return { ok: false, message: "Stored Slack message search is unavailable; no live search was performed." };
+ }
if (deps.surfaceSearch) {
const hits = await deps.surfaceSearch.search({
surface: input.surface ?? "unknown",
diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.ts
index 03b4d361e..f728ca7f6 100644
--- a/src/harness/agent-tools.ts
+++ b/src/harness/agent-tools.ts
@@ -2688,7 +2688,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):
"What to do: post (reply HERE, in this conversation — the normal way to answer), reach " +
"(send to a DIFFERENT audience: a teammate DM, another channel, a group — the ONLY way to " +
"leave this conversation), react (emoji on a message), edit/delete (revise/retract your " +
- "OWN message), read_thread (pull this thread's live messages), whats_new (pointers to what " +
+ "OWN message), read_thread (read stored thread messages, with live fallback for missing context), whats_new (pointers to what " +
"changed), search (find messages), read_members (the roster), read_file (a shared file's " +
"contents by reference).",
},
@@ -2930,8 +2930,18 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):
const messages = r.messages ?? [];
return recordExternalResult(
callId,
- { tool: surfaceName, action: "read_thread", ok: true, count: messages.length },
- text(messages.length ? JSON.stringify(messages, null, 2) : "[no messages in this thread]"),
+ {
+ tool: surfaceName,
+ action: "read_thread",
+ ok: true,
+ count: messages.length,
+ ...(r.message ? { note: r.message } : {}),
+ },
+ text(
+ [messages.length ? JSON.stringify(messages, null, 2) : "[no messages in this thread]", r.message]
+ .filter(Boolean)
+ .join("\n"),
+ ),
"surface thread",
);
}
@@ -2965,9 +2975,10 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):
ok: true,
hereNew: here,
activeSubConversations: others,
+ ...(r.message ? { note: r.message } : {}),
...(r.latest ? { latest: r.latest } : {}),
},
- text(line),
+ text([line, r.message].filter(Boolean).join("\n")),
);
}
case "search": {
@@ -3013,9 +3024,10 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):
action: "search",
ok: true,
count: hits.length,
+ ...(r.message ? { note: r.message } : {}),
...(r.source ? { source: r.source } : {}),
},
- text(body),
+ text([body, r.message].filter(Boolean).join("\n")),
"surface search",
);
}
diff --git a/src/index.ts b/src/index.ts
index 1890d8e4b..b39b49496 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -95,6 +95,7 @@ const slackRuntime = createSlackRuntimeReconciler({
...process.env,
SLACK_BOT_TOKEN: stored.botToken,
SLACK_APP_TOKEN: stored.appToken,
+ SLACK_EVENTS_MODE: stored.appToken ? "socket" : process.env.SLACK_EVENTS_MODE,
},
stored.installId && managedSlack ? (staging) => managedSlack.receiver(stored.installId!, staging) : undefined,
);
diff --git a/src/slack/config.ts b/src/slack/config.ts
index 0aea51432..69b99e143 100644
--- a/src/slack/config.ts
+++ b/src/slack/config.ts
@@ -4,6 +4,7 @@ import { botIdentityFromEnv } from "./delivery.ts";
import { normalizeAllowFrom, parseAllowFrom } from "./allow-from.ts";
export const NO_RETRY = { retryConfig: { retries: 0 } } as const;
+export const HISTORY_NO_RETRY = { ...NO_RETRY, rejectRateLimitedCalls: true } as const;
export interface SlackPluginConfig {
installationId?: string;
diff --git a/src/slack/conversation-view.ts b/src/slack/conversation-view.ts
index 031adf9ae..4a1a7f578 100644
--- a/src/slack/conversation-view.ts
+++ b/src/slack/conversation-view.ts
@@ -1,3 +1,5 @@
+import { slackHistoryRateLimitMessage } from "./history-rate-limit.ts";
+import type { SlackHistoryReader } from "./history.ts";
import { swallow } from "../util/errors.ts";
import {
type ActorAssertion,
@@ -14,13 +16,11 @@ import {
} from "./lib.ts";
import type { BotIdentity, Directory } from "./directory.ts";
import type { SlackConversationKind } from "./messaging.ts";
-import { type SlackHistoryMessage, parseMessageList } from "./payloads.ts";
+import { type SlackHistoryMessage } from "./payloads.ts";
import { messageWithForwardedContent } from "./forwards.ts";
export const RECENT_HISTORY_LIMIT = 200;
export const RECENT_THREAD_LIMIT = 200;
-const MAX_EXPANDED_THREADS = 5;
-const EXPANDED_THREAD_REPLY_LIMIT = RECENT_THREAD_LIMIT;
export const MAX_NAME_LOOKUPS = 10;
const RECENT_KEEP_SUBTYPES = new Set(["file_share", "bot_message", "thread_broadcast"]);
const MEMBERS_SHOW_MAX = 40;
@@ -43,7 +43,15 @@ export interface ConversationSerializer {
): Promise<RecentMessage[]>;
serializeSlackConversation(
client: any,
- inc: { kind: "dm" | "channel"; channel: string; threadTs?: string; ts: string; files: SlackFile[] },
+ inc: {
+ kind: "dm" | "channel";
+ channel: string;
+ threadTs?: string;
+ ts: string;
+ files: SlackFile[];
+ rawText?: string;
+ userId?: string;
+ },
ctx: {
audience: ActorAssertion[];
channelName?: string;
@@ -60,6 +68,8 @@ export function createConversationSerializer(deps: {
directory: Directory;
externalParticipantsEnabled(): Promise<boolean>;
recentMessages?: number;
+ readHistory: SlackHistoryReader;
+ historyRateLimitOptions?: { managed?: boolean; setupUrl?: string };
}): ConversationSerializer {
const { ids, directory, externalParticipantsEnabled } = deps;
const RECENT_MESSAGE_WINDOW = deps.recentMessages
@@ -115,40 +125,6 @@ export function createConversationSerializer(deps: {
]);
}
- async function fetchRawConversation(
- client: any,
- channel: string,
- threadTs: string | undefined,
- ): Promise<SlackHistoryMessage[]> {
- try {
- if (threadTs) {
- return parseMessageList(
- await client.conversations.replies({ channel, ts: threadTs, limit: RECENT_THREAD_LIMIT }),
- ).messages;
- }
- const history = parseMessageList(await client.conversations.history({ channel, limit: RECENT_HISTORY_LIMIT }))
- .messages.slice()
- .reverse();
- const threadParents = history.filter((m) => m.ts && Number(m.reply_count) > 0).slice(-MAX_EXPANDED_THREADS);
- const expanded = await Promise.all(
- threadParents.map(async (p) => {
- try {
- return parseMessageList(
- await client.conversations.replies({ channel, ts: p.ts, limit: EXPANDED_THREAD_REPLY_LIMIT }),
- ).messages;
- } catch {
- return [];
- }
- }),
- );
- const byTs = new Map<string, SlackHistoryMessage>();
- for (const m of [...history, ...expanded.flat()]) if (m?.ts) byTs.set(m.ts, m);
- return [...byTs.values()];
- } catch {
- return [];
- }
- }
-
async function shapeRecentMessages(
client: any,
raw: SlackHistoryMessage[],
@@ -181,7 +157,15 @@ export function createConversationSerializer(deps: {
async function serializeSlackConversation(
client: any,
- inc: { kind: "dm" | "channel"; channel: string; threadTs?: string; ts: string; files: SlackFile[] },
+ inc: {
+ kind: "dm" | "channel";
+ channel: string;
+ threadTs?: string;
+ ts: string;
+ files: SlackFile[];
+ rawText?: string;
+ userId?: string;
+ },
ctx: {
audience: ActorAssertion[];
channelName?: string;
@@ -208,7 +192,19 @@ export function createConversationSerializer(deps: {
const slackId = ctx.slackIdsByPrincipal?.get(a.externalId);
if (slackId) nameById.set(slackId, a.displayName);
}
- const raw = await fetchRawConversation(client, inc.channel, inc.threadTs);
+ const page = await deps.readHistory(client, inc.channel, inc.threadTs).catch((error) => {
+ swallow("slack: conversation context", error);
+ return {
+ raw: [] as SlackHistoryMessage[],
+ hasMore: true,
+ note:
+ slackHistoryRateLimitMessage(error, deps.historyRateLimitOptions) ??
+ "Slack context could not be read; earlier messages may be missing.",
+ };
+ });
+ const raw = page.raw;
+ if (inc.rawText !== undefined && !raw.some((m) => m.ts === inc.ts))
+ raw.push({ ts: inc.ts, text: inc.rawText, user: inc.userId, thread_ts: inc.threadTs, files: inc.files });
const messages = recentWindow(
await shapeRecentMessages(client, raw, inc.ts, nameById),
RECENT_MESSAGE_WINDOW,
@@ -272,6 +268,7 @@ export function createConversationSerializer(deps: {
files,
omittedFiles,
nameById,
+ ...("note" in page && page.note ? { contextNote: page.note } : {}),
};
return { view, earlierFiles };
}
diff --git a/src/slack/conversation.ts b/src/slack/conversation.ts
index f51fac81b..442d8036e 100644
--- a/src/slack/conversation.ts
+++ b/src/slack/conversation.ts
@@ -135,6 +135,7 @@ interface ConversationMember {
}
export interface ConversationView {
+ contextNote?: string;
channel: { name?: string; kind: "dm" | "channel" | "group"; isPrivate?: boolean };
members: readonly ConversationMember[];
messages: readonly RecentMessage[];
@@ -246,7 +247,7 @@ export function renderConversationView(view: ConversationView): RenderedConversa
? "Files too big to view this turn: " + view.omittedFiles.map((f) => f.name).join(", ") + "."
: "";
- const header = [fileLine, omittedLine, where, who, here].filter(Boolean).join(" ");
+ const header = [fileLine, omittedLine, where, who, here, view.contextNote].filter(Boolean).join(" ");
const detectContext = msgs
.filter((m) => !m.isBot && !m.isSelf && !m.isTrigger)
diff --git a/src/slack/events.ts b/src/slack/events.ts
index e6b3eb4e4..a99677501 100644
--- a/src/slack/events.ts
+++ b/src/slack/events.ts
@@ -196,7 +196,12 @@ export function registerSlackEvents(
const textChanged = m.previous_message?.text === undefined || m.previous_message.text !== m.message.text;
if (shouldProcessMessage(m.message, ids.botUserId, ids.ownBotId))
await mirrorMessageEvent({ ...m.message, channel: m.channel, channel_type: m.channel_type }, client, {
- ...(textChanged ? { editedAt: Date.now() } : {}),
+ ...(textChanged
+ ? {
+ editedAt:
+ Number(m.message.edited?.ts) > 0 ? Math.round(Number(m.message.edited!.ts) * 1000) : Date.now(),
+ }
+ : {}),
...(m.channel_type === "im" ? { kind: "dm" as const } : {}),
});
return;
diff --git a/src/slack/history-rate-limit.ts b/src/slack/history-rate-limit.ts
new file mode 100644
index 000000000..bd4cd9873
--- /dev/null
+++ b/src/slack/history-rate-limit.ts
@@ -0,0 +1,24 @@
+export function slackHistoryRateLimitMessage(
+ error: unknown,
+ opts: { setupUrl?: string; managed?: boolean } = {},
+): string | undefined {
+ if (!error || typeof error !== "object") return undefined;
+ const value = error as { code?: unknown; retryAfter?: unknown; data?: { error?: unknown } };
+ if (value.code !== "slack_webapi_rate_limited_error" && value.data?.error !== "ratelimited") return undefined;
+ const seconds = Number(value.retryAfter);
+ const retry =
+ Number.isFinite(seconds) && seconds > 0 ? ` Retry after ${Math.ceil(seconds)} seconds.` : " Try again shortly.";
+ const message = `Slack is temporarily limiting history reads for this workspace. Earlier context may be incomplete.${retry}`;
+ if (!opts.managed) return message;
+ let setupUrl: string | undefined;
+ try {
+ const url = new URL(opts.setupUrl ?? "");
+ if (url.protocol === "https:" && !url.username && !url.password) setupUrl = url.href;
+ } catch {
+ setupUrl = undefined;
+ }
+ const setup = setupUrl
+ ? `[set up a workspace-owned Slack app](${setupUrl})`
+ : "set up a workspace-owned Slack app in QM's Slack settings";
+ return `${message} A workspace admin can ${setup} for this company. Keep using the available context; do not repeatedly retry the history request.`;
+}
diff --git a/src/slack/history.ts b/src/slack/history.ts
new file mode 100644
index 000000000..725b3ebeb
--- /dev/null
+++ b/src/slack/history.ts
@@ -0,0 +1,122 @@
+import { decodeSlackEntities, mentionsBot } from "./lib.ts";
+import { slackHistoryRateLimitMessage } from "./history-rate-limit.ts";
+import type { SlackCoreClient } from "../api/slack-core-client.ts";
+import type { BotIdentity } from "./directory.ts";
+import type { SlackHistoryMessage } from "./payloads.ts";
+import { parseMessageList } from "./payloads.ts";
+import { swallow } from "../util/errors.ts";
+
+interface SlackHistoryPage {
+ raw: SlackHistoryMessage[];
+ hasMore: boolean;
+ note?: string;
+}
+
+export type SlackHistoryReader = (
+ client: any,
+ channel: string,
+ threadTs?: string,
+ before?: string,
+) => Promise<SlackHistoryPage>;
+
+const MIRROR_CONTEXT_NOTE =
+ "Context comes from stored Slack events. Earlier messages, missed events, reactions, and attachment details may be absent; this is not a complete Slack history.";
+
+export function createSlackHistoryReader(deps: {
+ core: SlackCoreClient;
+ ids: BotIdentity;
+ managed?: boolean;
+ setupUrl?: string;
+ historyClient?: { conversations: { history(args: any): Promise<unknown>; replies(args: any): Promise<unknown> } };
+}): SlackHistoryReader {
+ return async (client, channel, threadTs, before) => {
+ const historyClient = deps.historyClient ?? client;
+ let mirrored: SlackHistoryMessage[] = [];
+ const deleted = new Set<string>();
+ if (deps.core.readSurfaceMessages) {
+ try {
+ const options = { limit: 200, includeDeleted: true, ...(before ? { before } : {}) };
+ const rows = threadTs
+ ? (
+ await Promise.all([
+ deps.core.readSurfaceMessages(channel, { ...options, sub: threadTs }),
+ deps.core.readSurfaceMessages(channel, { at: threadTs, includeDeleted: true }),
+ ])
+ ).flat()
+ : await deps.core.readSurfaceMessages(channel, options);
+ for (const row of rows) if (row.deleted) deleted.add(row.ts);
+ mirrored = rows
+ .filter((m) => !m.deleted && (!before || m.ts < before))
+ .map((m) => ({
+ ts: m.ts,
+ text: m.text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"),
+ ...(m.mentionsSelf ? { mentionsSelf: true } : {}),
+ ...(m.sub ? { thread_ts: m.sub } : {}),
+ ...(m.self || m.authorId ? { user: m.self ? deps.ids.botUserId : m.authorId } : {}),
+ ...(m.authorName ? { username: m.authorName } : {}),
+ ...(m.bot ? { bot_id: m.self ? deps.ids.ownBotId : "mirrored-bot" } : {}),
+ ...(m.files?.length
+ ? { files: m.files.map((f) => ({ id: f.fileId, name: f.name, mimetype: f.mimetype })) }
+ : {}),
+ }));
+ if (mirrored.length && (!threadTs || rows.some((m) => m.ts === threadTs) || before)) {
+ return { raw: mirrored, hasMore: rows.length >= 200, note: MIRROR_CONTEXT_NOTE };
+ }
+ } catch (error) {
+ swallow("slack: mirror context read", error);
+ }
+ }
+ try {
+ const paging = { channel, limit: 200, ...(before ? { latest: before, inclusive: false } : {}) };
+ const page = parseMessageList(
+ threadTs
+ ? await historyClient.conversations.replies({ ...paging, ts: threadTs })
+ : await historyClient.conversations.history(paging),
+ );
+ if (page.messages.length && deps.core.rememberSurfaceHistory) {
+ await deps.core
+ .rememberSurfaceHistory(
+ page.messages
+ .filter((m) => m.ts)
+ .map((m) => ({
+ container: channel,
+ ts: m.ts!,
+ ...(m.thread_ts && m.thread_ts !== m.ts ? { sub: m.thread_ts } : {}),
+ ...(m.user ? { authorId: m.user } : {}),
+ ...(m.username ? { authorName: m.username } : {}),
+ text: decodeSlackEntities(String(m.text ?? "")),
+ ...(mentionsBot(String(m.text ?? ""), deps.ids.botUserId) ? { mentionsSelf: true } : {}),
+ ...(m.user === deps.ids.botUserId ? { self: true } : {}),
+ ...(m.bot_id ? { bot: true } : {}),
+ ...(Number(m.edited?.ts) > 0 ? { editedAt: Math.round(Number(m.edited!.ts) * 1000) } : {}),
+ handled: true,
+ ...(m.files?.length
+ ? {
+ files: m.files
+ .filter((f) => f.id)
+ .map((f) => ({ fileId: f.id!, name: f.name, mimetype: f.mimetype })),
+ }
+ : {}),
+ })),
+ )
+ .catch((error) => swallow("slack: history mirror ingest", error));
+ }
+ const byTs = new Map<string, SlackHistoryMessage>();
+ for (const message of [...page.messages, ...mirrored])
+ if (message.ts && !deleted.has(message.ts)) byTs.set(message.ts, message);
+ return {
+ raw: [...byTs.values()],
+ hasMore: page.hasMore,
+ ...(page.hasMore ? { note: "Slack history is truncated; older messages may be absent." } : {}),
+ };
+ } catch (error) {
+ if (!mirrored.length) throw error;
+ swallow("slack: incomplete mirror history fallback", error);
+ return {
+ raw: mirrored,
+ hasMore: true,
+ note: [MIRROR_CONTEXT_NOTE, slackHistoryRateLimitMessage(error, deps)].filter(Boolean).join(" "),
+ };
+ }
+ };
+}
diff --git a/src/slack/index.ts b/src/slack/index.ts
index 85f0e6d1f..8716ce39c 100644
--- a/src/slack/index.ts
+++ b/src/slack/index.ts
@@ -1,3 +1,4 @@
+import { createSlackHistoryReader } from "./history.ts";
import { errMessage, swallow, swallowAs } from "../util/errors.ts";
import { createEnvelopeStaging } from "./envelope-staging.ts";
import { createSweeper } from "../util/sweeper.ts";
@@ -8,6 +9,7 @@ import { installDevIntrospection } from "./dev-introspection.ts";
import { setDefaultBotIdentity, createSurfaceHeaderEnsurer, type SurfaceHeaderClient } from "./delivery.ts";
import {
NO_RETRY,
+ HISTORY_NO_RETRY,
type SlackPluginConfig,
normalizeSlackApiUrl,
slackAccountConfigsFromEnv,
@@ -206,7 +208,15 @@ export async function startSlackPlugin(
...(cfg.userCacheTtlMs ? { userCacheTtlMs: cfg.userCacheTtlMs } : {}),
});
const mirror = createMirror({ core, ids, directory, externalParticipantsEnabled });
+ const historyRateLimitOptions = {
+ managed: Boolean(cfg.installationId),
+ ...(cfg.webUiPublicUrl ? { setupUrl: `${cfg.webUiPublicUrl.replace(/\/$/, "")}/admin/?setup=slack` } : {}),
+ };
+ const historyClient = new WebClient(BOT_TOKEN, { ...CLIENT_OPTIONS, ...HISTORY_NO_RETRY });
+ const readHistory = createSlackHistoryReader({ core, ids, historyClient, ...historyRateLimitOptions });
const serializer = createConversationSerializer({
+ readHistory,
+ historyRateLimitOptions,
ids,
directory,
externalParticipantsEnabled,
@@ -256,6 +266,7 @@ export async function startSlackPlugin(
})();
});
const handler = createTurnHandler({
+ readHistory,
core,
flow,
directory,
@@ -311,6 +322,9 @@ export async function startSlackPlugin(
ensureHeader,
});
const surfaceContext = createSurfaceContextFulfiller({
+ historyClient,
+ readHistory,
+ historyRateLimitOptions,
core,
directory,
serializer,
diff --git a/src/slack/message-gating.ts b/src/slack/message-gating.ts
index b07597333..4550ce40c 100644
--- a/src/slack/message-gating.ts
+++ b/src/slack/message-gating.ts
@@ -5,7 +5,7 @@ export function mentionsBot(text: string, botUserId: string): boolean {
}
export function threadHasBotStake(
- messages: readonly { user?: string; bot_id?: string; text?: string }[],
+ messages: readonly { user?: string; bot_id?: string; text?: string; mentionsSelf?: boolean }[],
botUserId: string,
ownBotId = "",
): boolean {
@@ -15,6 +15,7 @@ export function threadHasBotStake(
const bot = m.bot_id ? String(m.bot_id) : "";
const text = m.text ? String(m.text) : "";
return Boolean(
+ m.mentionsSelf ||
(botUserId && user === botUserId) ||
(ownBotId && bot === ownBotId) ||
(botUserId && mentionsBot(text, botUserId)),
diff --git a/src/slack/mirror.ts b/src/slack/mirror.ts
index d09499139..d91d4464d 100644
--- a/src/slack/mirror.ts
+++ b/src/slack/mirror.ts
@@ -106,7 +106,8 @@ export function createMirror(deps: {
}
if (!gate.allowed) return;
}
- const raw = messageWithForwardedContent(m).text;
+ const content = messageWithForwardedContent(m);
+ const raw = content.text;
const { text, mentions } = await resolveTextMentions(client, decodeSlackEntities(raw));
await pushSurfaceEvents([
{
@@ -116,6 +117,13 @@ export function createMirror(deps: {
...(m.user ? { authorId: String(m.user) } : {}),
...(m.bot_profile?.name || m.username ? { authorName: String(m.bot_profile?.name || m.username) } : {}),
text,
+ ...(content.files.length
+ ? {
+ files: content.files
+ .filter((f) => f.id)
+ .map((f) => ({ fileId: f.id!, name: f.name, mimetype: f.mimetype })),
+ }
+ : {}),
...(Object.keys(mentions).length ? { mentions } : {}),
...(m.bot_id || m.bot_profile ? { bot: true } : {}),
...(mentionsBot(raw, ids.botUserId) ? { mentionsSelf: true } : {}),
diff --git a/src/slack/payloads.ts b/src/slack/payloads.ts
index 595d84269..6147d7a35 100644
--- a/src/slack/payloads.ts
+++ b/src/slack/payloads.ts
@@ -29,6 +29,7 @@ export interface SlackMessageEvent {
client_msg_id?: string;
text?: string;
ts: string;
+ edited?: { ts?: string };
thread_ts?: string;
deleted_ts?: string;
files: SlackFile[];
@@ -141,6 +142,8 @@ export function parseBlockAction<T extends string>(
}
export interface SlackHistoryMessage {
+ edited?: { ts?: string };
+ mentionsSelf?: boolean;
ts?: string;
user?: string;
bot_id?: string;
diff --git a/src/slack/surface-context.ts b/src/slack/surface-context.ts
index d8d0761fc..bf34c56c9 100644
--- a/src/slack/surface-context.ts
+++ b/src/slack/surface-context.ts
@@ -1,3 +1,5 @@
+import { slackHistoryRateLimitMessage } from "./history-rate-limit.ts";
+import type { SlackHistoryReader } from "./history.ts";
import { swallow, swallowAs } from "../util/errors.ts";
import { WebClient } from "@slack/web-api";
import {
@@ -29,6 +31,9 @@ export function createSurfaceContextFulfiller(deps: {
trustedFileHost?: string;
userToken?: string;
clientOptions: Record<string, unknown>;
+ readHistory?: SlackHistoryReader;
+ historyClient?: any;
+ historyRateLimitOptions?: { managed?: boolean; setupUrl?: string };
}): { fulfillSurfaceContext(client: any, r: SurfaceContextRequest): Promise<void> } {
const { core, directory, serializer, botToken, trustedFileHost, userToken, clientOptions } = deps;
@@ -71,7 +76,8 @@ export function createSurfaceContextFulfiller(deps: {
channel: string,
threadTs: string | undefined,
before: string | undefined,
- ): Promise<{ raw: SlackHistoryMessage[]; hasMore: boolean }> {
+ ): Promise<{ raw: SlackHistoryMessage[]; hasMore: boolean; note?: string }> {
+ if (deps.readHistory) return deps.readHistory(client, channel, threadTs, before);
const page = before ? { latest: before, inclusive: false } : {};
if (threadTs) {
const { messages, hasMore } = parseMessageList(
@@ -91,6 +97,7 @@ export function createSurfaceContextFulfiller(deps: {
ts: string,
threadTs: string | undefined,
): Promise<SlackHistoryMessage | undefined> {
+ client = deps.historyClient ?? client;
if (threadTs) {
const res = await client.conversations.replies({ channel, ts: threadTs, oldest: ts, inclusive: true, limit: 2 });
const hit = parseMessageList(res).messages.find((m) => m?.ts === ts);
@@ -224,29 +231,48 @@ export function createSurfaceContextFulfiller(deps: {
}
const count = Math.max(1, Math.min(RECENT_THREAD_LIMIT, Number(q.count) || 100));
const before = typeof q.before === "string" && q.before ? q.before : undefined;
- const [chanPage, threadPage] = await Promise.all([
+ const outcomes = await Promise.allSettled([
fetchContextHistory(client, channel, undefined, before),
threadTs
? fetchContextHistory(client, channel, threadTs, before)
: Promise.resolve<{ raw: SlackHistoryMessage[]; hasMore: boolean }>({ raw: [], hasMore: false }),
]);
const byTs = new Map<string, SlackHistoryMessage>();
- for (const m of [...chanPage.raw, ...threadPage.raw]) if (m?.ts) byTs.set(m.ts, m);
+ const notes = new Set<string>();
+ let hasMore = false;
+ for (const outcome of outcomes) {
+ if (outcome.status === "rejected") {
+ hasMore = true;
+ notes.add(
+ slackHistoryRateLimitMessage(outcome.reason, deps.historyRateLimitOptions) ??
+ "Some Slack context could not be read; earlier messages may be missing.",
+ );
+ continue;
+ }
+ for (const message of outcome.value.raw) if (message.ts) byTs.set(message.ts, message);
+ hasMore ||= outcome.value.hasMore;
+ if ("note" in outcome.value && outcome.value.note) notes.add(outcome.value.note);
+ }
const raw = [...byTs.values()];
- const hasMore = chanPage.hasMore || threadPage.hasMore;
+ const failure = outcomes.find((outcome) => outcome.status === "rejected");
+ if (!raw.length && failure?.status === "rejected") throw failure.reason;
+ const note = [...notes].join(" ");
const nameById = new Map<string, string>();
const shaped = await serializer.shapeRecentMessages(client, raw, "", nameById);
- await post(
- buildContextWindow(shaped, {
+ await post({
+ ...buildContextWindow(shaped, {
count,
...(typeof q.match === "string" && q.match ? { match: q.match } : {}),
scanHasMore: hasMore,
nameById,
}),
- );
+ ...(note ? { note } : {}),
+ });
} catch (err) {
const code = slackErrorCode(err);
- let msg = `Slack read failed: ${(err as Error).message}`;
+ let msg =
+ slackHistoryRateLimitMessage(err, deps.historyRateLimitOptions) ??
+ `Slack read failed: ${(err as Error).message}`;
if (code === "not_in_channel") msg = "I'm not a member of that channel — ask someone to /invite me there";
else if (code === "channel_not_found") msg = "I can't see that channel";
await post({ error: msg });
diff --git a/src/slack/turn-handler.ts b/src/slack/turn-handler.ts
index 40471c6fe..5485e1111 100644
--- a/src/slack/turn-handler.ts
+++ b/src/slack/turn-handler.ts
@@ -1,3 +1,4 @@
+import type { SlackHistoryReader } from "./history.ts";
import { performance } from "node:perf_hooks";
import { slackFailureText } from "./turn-flow.ts";
import { errMessage, swallowAs } from "../util/errors.ts";
@@ -128,6 +129,7 @@ export function createTurnHandler(deps: {
flow: TurnFlow;
directory: Directory;
mirror: Mirror;
+ readHistory?: SlackHistoryReader;
serializer: ConversationSerializer;
approvals: Approvals;
ackEmoji: AckEmojiPicker;
@@ -171,8 +173,10 @@ export function createTurnHandler(deps: {
const cached = threads.get(channel, threadTs);
if (cached !== undefined) return cached;
try {
- const res = await client.conversations.replies({ channel, ts: threadTs, limit: 200 });
- const present = threadHasBotStake(res.messages ?? [], ids.botUserId, ids.ownBotId);
+ const messages = deps.readHistory
+ ? (await deps.readHistory(client, channel, threadTs)).raw
+ : ((await client.conversations.replies({ channel, ts: threadTs, limit: 200 })).messages ?? []);
+ const present = threadHasBotStake(messages, ids.botUserId, ids.ownBotId);
threads.mark(channel, threadTs, present);
return present;
} catch {
@@ -393,7 +397,7 @@ export function createTurnHandler(deps: {
{
const containerName = inc.kind === "dm" ? actor.displayName?.trim() || undefined : channelName;
- void mirrorMessageEvent(
+ await mirrorMessageEvent(
{
channel: inc.channel,
ts: inc.ts,
diff --git a/src/surface-cache/surface-cache.ts b/src/surface-cache/surface-cache.ts
index c000508ae..b5e7c56e9 100644
--- a/src/surface-cache/surface-cache.ts
+++ b/src/surface-cache/surface-cache.ts
@@ -7,6 +7,7 @@ import type {
ContainerState,
ContainerSummary,
LiveFallback,
+ IngestEvent,
SurfaceCache,
} from "./types.ts";
@@ -26,6 +27,12 @@ const MAX_READ_LIMIT = 500;
const DEFAULT_SEARCH_LIMIT = 50;
const DEFAULT_THREADS_LIMIT = 50;
+function normalizeEvent(event: IngestEvent): IngestEvent {
+ return JSON.parse(
+ JSON.stringify(event, (_key, value) => (typeof value === "string" ? value.replace(/\u0000/g, "") : value)),
+ ) as IngestEvent;
+}
+
function clampLimit(limit: number | undefined, fallback: number): number {
return Math.max(1, Math.min(MAX_READ_LIMIT, Math.floor(limit ?? fallback)));
}
@@ -128,6 +135,7 @@ export function createPostgresSurfaceCache(
...(r.deleted ? { deleted: true } : {}),
...(r.deleted_at != null ? { deletedAt: Number(r.deleted_at) } : {}),
...(r.handled ? { handled: true } : {}),
+ ...(Array.isArray(r.files) && r.files.length ? { files: r.files as CachedMessage["files"] } : {}),
createdAt: Number(r.created_at),
};
}
@@ -140,7 +148,8 @@ export function createPostgresSurfaceCache(
let upserted = 0;
try {
await client.query("BEGIN");
- for (const e of events) {
+ for (const event of events) {
+ const e = normalizeEvent(event);
if (!e.container || !e.ts) continue;
const res = await client.query(
`INSERT INTO channel_messages(org_id, container, ts, sub, author_id, author_name, text, mentions, self, bot, mentions_self, edited_at, deleted, handled, created_at, deleted_at)
@@ -149,8 +158,8 @@ export function createPostgresSurfaceCache(
sub = COALESCE(EXCLUDED.sub, channel_messages.sub),
author_id = COALESCE(EXCLUDED.author_id, channel_messages.author_id),
author_name = COALESCE(EXCLUDED.author_name, channel_messages.author_name),
- text = CASE WHEN EXCLUDED.deleted THEN channel_messages.text ELSE EXCLUDED.text END,
- mentions = CASE WHEN EXCLUDED.deleted THEN channel_messages.mentions ELSE COALESCE(EXCLUDED.mentions, channel_messages.mentions) END,
+ text = CASE WHEN EXCLUDED.deleted OR COALESCE(EXCLUDED.edited_at, 0) < COALESCE(channel_messages.edited_at, 0) THEN channel_messages.text ELSE EXCLUDED.text END,
+ mentions = CASE WHEN EXCLUDED.deleted OR COALESCE(EXCLUDED.edited_at, 0) < COALESCE(channel_messages.edited_at, 0) THEN channel_messages.mentions ELSE COALESCE(EXCLUDED.mentions, channel_messages.mentions) END,
self = channel_messages.self OR EXCLUDED.self,
bot = channel_messages.bot OR EXCLUDED.bot,
mentions_self = channel_messages.mentions_self OR EXCLUDED.mentions_self,
@@ -228,6 +237,10 @@ export function createPostgresSurfaceCache(
const limit = clampLimit(opts.limit, DEFAULT_READ_LIMIT);
const conds = ["org_id = $1", "container = $2"];
const args: unknown[] = [orgId, container];
+ if (opts.at) {
+ args.push(opts.at);
+ conds.push(`ts = $${args.length}`);
+ }
if (opts.sub) {
args.push(opts.sub);
conds.push(`sub = $${args.length}`);
@@ -243,7 +256,7 @@ export function createPostgresSurfaceCache(
if (!opts.includeDeleted) conds.push("deleted = FALSE");
args.push(limit);
const rows = await q(
- `SELECT * FROM channel_messages WHERE ${conds.join(" AND ")} ORDER BY ts DESC LIMIT $${args.length}`,
+ `SELECT channel_messages.*, (SELECT json_agg(json_build_object('fileId', f.file_id, 'name', f.name, 'mimetype', f.mimetype)) FROM channel_files f WHERE f.org_id = channel_messages.org_id AND f.container = channel_messages.container AND f.ts = channel_messages.ts) AS files FROM channel_messages WHERE ${conds.join(" AND ")} ORDER BY ts DESC LIMIT $${args.length}`,
args,
);
const hit = rows.map(rowToMessage).reverse();
@@ -404,7 +417,8 @@ export function createMemorySurfaceCache(opts: { liveFallback?: LiveFallback } =
async ingest(events) {
const now = Date.now();
let upserted = 0;
- for (const e of events) {
+ for (const event of events) {
+ const e = normalizeEvent(event);
if (!e.container || !e.ts) continue;
const m = containerMsgs(e.container);
const existing = m.get(e.ts);
@@ -435,6 +449,7 @@ export function createMemorySurfaceCache(opts: { liveFallback?: LiveFallback } =
});
upserted++;
}
+ if (existing && e.handled && !existing.handled) m.set(e.ts, { ...m.get(e.ts)!, handled: true });
if (e.files?.length) {
const k = key(e.container);
const arr = files.get(k) ?? [];
@@ -476,12 +491,18 @@ export function createMemorySurfaceCache(opts: { liveFallback?: LiveFallback } =
async readMessages(container, o = {}) {
const limit = clampLimit(o.limit, DEFAULT_READ_LIMIT);
let all = [...containerMsgs(container).values()];
+ if (o.at) all = all.filter((x) => x.ts === o.at);
if (o.sub) all = all.filter((x) => x.sub === o.sub);
if (o.after) all = all.filter((x) => x.ts > o.after!);
if (o.before) all = all.filter((x) => x.ts < o.before!);
if (!o.includeDeleted) all = all.filter((x) => !x.deleted);
all.sort(compareTs);
- const hit = all.slice(-limit);
+ const hit = all.slice(-limit).map((m) => {
+ const attached = (files.get(key(container)) ?? []).filter((f) => f.ts === m.ts);
+ return attached.length
+ ? { ...m, files: attached.map(({ fileId, name, mimetype }) => ({ fileId, name, mimetype })) }
+ : m;
+ });
if (hit.length === 0 && liveFallback && !o.noFallback && !o.before) {
const live = await liveFallback(container, o);
if (live) return live;
diff --git a/src/surface-cache/types.ts b/src/surface-cache/types.ts
index eccb2a913..3f82c9050 100644
--- a/src/surface-cache/types.ts
+++ b/src/surface-cache/types.ts
@@ -5,6 +5,7 @@ export interface CachedMessage {
authorId?: string;
authorName?: string;
text: string;
+ files?: Array<{ fileId: string; name?: string; mimetype?: string }>;
mentions?: Record<string, string>;
self?: boolean;
bot?: boolean;
@@ -69,6 +70,7 @@ export interface ContainerSummary extends ContainerState {
}
export interface ReadMessagesOpts {
+ at?: string;
sub?: string;
limit?: number;
after?: string;
diff --git a/src/surfaces/slack-installation.ts b/src/surfaces/slack-installation.ts
index fd6b11ca9..5fa66d3ec 100644
--- a/src/surfaces/slack-installation.ts
+++ b/src/surfaces/slack-installation.ts
@@ -2,6 +2,7 @@ import type { DurableMap } from "../persistence/durable-map.ts";
import { decryptSecret, deriveConnectorKey, encryptSecret } from "../connectors/connector-client-store.ts";
interface ActiveSlackInstallation {
+ serviceBlocked?: boolean;
orgId: string;
disabled: false;
botTokenEnc: string;
@@ -18,6 +19,7 @@ interface ActiveSlackInstallation {
interface DisabledSlackInstallation {
installedAt?: number;
+ serviceBlocked?: boolean;
orgId: string;
disabled: true;
updatedAt: number;
@@ -73,6 +75,7 @@ export interface SlackInstallationStore {
teamName?: string;
}): Promise<boolean>;
disableManaged(installId: string): Promise<boolean>;
+ enableManaged(): Promise<boolean>;
}
export function createSlackInstallationStore(
@@ -114,10 +117,12 @@ export function createSlackInstallationStore(
return publicStatus(await map.get(orgId));
},
async set(input) {
+ if (!map.update) throw new Error("Atomic installation updates are required");
const updatedAt = Date.now();
const record: StoredSlackInstallation = {
orgId,
disabled: false,
+ serviceBlocked: true,
botTokenEnc: encryptSecret(input.botToken, key),
...(input.appToken ? { appTokenEnc: encryptSecret(input.appToken, key) } : {}),
...(input.appId ? { appId: input.appId } : {}),
@@ -128,8 +133,13 @@ export function createSlackInstallationStore(
updatedBy: input.updatedBy,
version: `${updatedAt}:${crypto.randomUUID()}`,
};
- await map.put(orgId, record);
- return publicStatus(record);
+ await map.putIfAbsent(orgId, record);
+ const stored = await map.update(orgId, (current) => ({
+ ...record,
+ ...(current.installedAt !== undefined ? { installedAt: current.installedAt } : {}),
+ }));
+ if (!stored) throw new Error("Slack installation disappeared during update");
+ return publicStatus(stored);
},
async setManaged(input) {
if (!map.update) throw new Error("Atomic installation updates are required");
@@ -142,6 +152,7 @@ export function createSlackInstallationStore(
});
let accepted = false;
await map.update(orgId, (record) => {
+ if (record.serviceBlocked || (!record.disabled && !record.installId)) return record;
if (!record.disabled && record.installId === input.installId) {
accepted =
record.teamId === input.teamId && record.appId === input.appId && record.installedAt === input.installedAt;
@@ -166,6 +177,18 @@ export function createSlackInstallationStore(
});
return accepted;
},
+ async enableManaged() {
+ if (!map.update) throw new Error("Atomic installation updates are required");
+ let accepted = true;
+ await map.update(orgId, (record) => {
+ if (!record.disabled && !record.installId) {
+ accepted = false;
+ return record;
+ }
+ return { ...record, serviceBlocked: false };
+ });
+ return accepted;
+ },
async disableManaged(installId) {
if (!map.update) throw new Error("Atomic installation updates are required");
let disabled = false;
@@ -188,6 +211,7 @@ export function createSlackInstallationStore(
const record = await map.update(orgId, (current) => ({
orgId,
disabled: true,
+ serviceBlocked: current.serviceBlocked || (!current.disabled && !current.installId),
...(current.installedAt ? { installedAt: current.installedAt } : {}),
updatedAt: Date.now(),
updatedBy,
@@ -264,8 +288,14 @@ export async function validateSlackInstallation(
fetchImpl: typeof fetch = fetch,
readSocketAppId: SlackSocketAppIdReader = readSlackSocketAppId,
): Promise<{ teamId?: string; teamName?: string }> {
- if (!botToken.startsWith("xoxb-")) throw new Error("bot token must start with xoxb-");
- if (!appToken.startsWith("xapp-")) throw new Error("app token must start with xapp-");
+ if (!botToken.startsWith("xoxb-"))
+ throw new Error(
+ "Bot token must start with xoxb-. Copy the Bot User OAuth Token from OAuth & Permissions after installing the app.",
+ );
+ if (!appToken.startsWith("xapp-"))
+ throw new Error(
+ "App token must start with xapp-. Generate an App-Level Token in Basic Information with connections:write.",
+ );
const call = async (method: string, token: string, formBody = ""): Promise<SlackValidationResponse> => {
const response = await fetchImpl(`https://slack.com/api/${method}`, {
method: "POST",
@@ -273,8 +303,33 @@ export async function validateSlackInstallation(
body: formBody,
signal: AbortSignal.timeout(10_000),
});
+ const label = method === "apps.connections.open" ? "App-level token" : "Bot token";
+ if (response.status === 429) {
+ const seconds = Number(response.headers.get("retry-after"));
+ throw new Error(
+ `Slack is temporarily rate-limiting validation. Try again${seconds > 0 && Number.isFinite(seconds) ? ` in ${Math.ceil(seconds)} seconds` : " shortly"}. Your existing connection has not changed.`,
+ );
+ }
const payload = (await response.json()) as SlackValidationResponse;
- if (!response.ok || !payload.ok) throw new Error(`${method} failed: ${payload.error ?? `HTTP ${response.status}`}`);
+ if (!response.ok || !payload.ok) {
+ if (["invalid_auth", "token_revoked", "not_authed", "account_inactive"].includes(payload.error ?? ""))
+ throw new Error(
+ `${label} was rejected by Slack. Copy a current token from the same installed Slack app and try again.`,
+ );
+ if (payload.error === "missing_scope")
+ throw new Error(
+ method === "apps.connections.open"
+ ? "App-level token needs connections:write. Generate a new token in Basic Information with that scope."
+ : "Bot token is missing permissions. Apply the provided manifest and reinstall the app in OAuth & Permissions.",
+ );
+ if (payload.error === "not_allowed_token_type")
+ throw new Error(
+ `${label} has the wrong token type. Use the Bot User OAuth Token (xoxb-) and App-Level Token (xapp-) from the setup guide.`,
+ );
+ throw new Error(
+ `${label} validation failed (${payload.error ?? `HTTP ${response.status}`}). Check that the app is installed and Socket Mode is enabled, then try again.`,
+ );
+ }
return payload;
};
const auth = await call("auth.test", botToken);
@@ -287,7 +342,10 @@ export async function validateSlackInstallation(
const connection = await call("apps.connections.open", appToken);
if (!connection.url) throw new Error("apps.connections.open returned no WebSocket URL");
const socketAppId = await readSocketAppId(connection.url);
- if (socketAppId !== botAppId) throw new Error("bot token and app token belong to different Slack apps");
+ if (socketAppId !== botAppId)
+ throw new Error(
+ "The bot token and app token belong to different Slack apps. Copy both tokens from the same app; your existing connection has not changed.",
+ );
return {
...(auth.team_id ? { teamId: auth.team_id } : {}),
...(auth.team ? { teamName: auth.team } : {}),
diff --git a/src/surfaces/slack-managed.ts b/src/surfaces/slack-managed.ts
index 0c2723e99..1c5f81d30 100644
--- a/src/surfaces/slack-managed.ts
+++ b/src/surfaces/slack-managed.ts
@@ -31,6 +31,8 @@ export function createManagedSlack(opts: {
};
return {
async start(): Promise<{ url: string }> {
+ if (!(await opts.store.enableManaged()))
+ throw new Error("Disconnect your own Slack app before installing the managed app");
const response = await (opts.fetchImpl ?? fetch)(new URL("/install/start", serviceUrl), {
method: "POST",
headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
diff --git a/src/wiring.ts b/src/wiring.ts
index 2273a03aa..67dedbc79 100644
--- a/src/wiring.ts
+++ b/src/wiring.ts
@@ -1834,6 +1834,7 @@ export function buildApp(
requestFire: (loopId) => void loopFire.fire(loopId, `loop:${loopId}:slack-event:${Date.now()}`).catch(() => {}),
});
const slackCore = createSlackCoreClient({
+ surfaceCache,
inboxEvent: (event) => inboxRealtime.onConversationEvent(event),
app,
leaderLease,
diff --git a/test/connector-byo-route.test.ts b/test/connector-byo-route.test.ts
index a4d3a9b9f..bac561f09 100644
--- a/test/connector-byo-route.test.ts
+++ b/test/connector-byo-route.test.ts
@@ -10,15 +10,27 @@ import { createInsecureTestServer } from "../src/api/server.ts";
import { buildApp, type BuiltApp } from "../src/wiring.ts";
import { testConfig } from "./support/test-config.ts";
+import { createManagedSlack } from "../src/surfaces/slack-managed.ts";
+
const ADMIN = { "content-type": "application/json", "x-admin-actor": "admin-alice@default-org" };
-function start(socketAppId = "A-ACME"): { base: string; built: BuiltApp; close: () => Promise<void> } {
+function start(socketAppId = "A-ACME", managed = false): { base: string; built: BuiltApp; close: () => Promise<void> } {
const built = buildApp(testConfig({ dataDir: mkdtempSync(join(tmpdir(), "byo-route-")) }));
const server = createInsecureTestServer(built.app, {
oauthStateSecret: "byo-route-oauth-state-secret",
replayDedupe: built.replayDedupe,
connectorTokens: built.connectorTokens,
slackInstallation: built.slackInstallation,
+ ...(managed
+ ? {
+ managedSlack: createManagedSlack({
+ serviceUrl: "https://bridge.example",
+ token: "test-token",
+ appId: "A123",
+ store: built.slackInstallation,
+ }),
+ }
+ : {}),
slackInstallationFetch: (async (input: string | URL | Request) => {
const url = String(input);
return new Response(
@@ -207,3 +219,36 @@ test("the catalog endpoint exposes per-provider setup guidance (no secrets)", as
await srv.close();
}
});
+
+test("managed deployments accept validated own apps and preserve credentials on invalid replacement", async () => {
+ const srv = start("A-ACME", true);
+ try {
+ await srv.built.slackInstallation.setManaged({
+ botToken: "xoxb-managed",
+ appId: "A123",
+ teamId: "T-ACME",
+ installId: "I1",
+ installedAt: 1,
+ });
+ const put = (botToken: string) =>
+ fetch(`${srv.base}/v1/admin/slack-installation`, {
+ method: "PUT",
+ headers: ADMIN,
+ body: JSON.stringify({ botToken, appToken: "xapp-own" }),
+ });
+ assert.equal((await put("invalid")).status, 400);
+ assert.equal((await srv.built.slackInstallation.get())?.botToken, "xoxb-managed");
+ assert.equal((await put("xoxb-own")).status, 200);
+ const status = (await (await fetch(`${srv.base}/v1/admin/slack-installation`, { headers: ADMIN })).json()) as {
+ source: string;
+ installAvailable: boolean;
+ createUrl: string;
+ };
+ assert.equal(status.source, "admin");
+ assert.equal(status.installAvailable, true);
+ assert.equal(new URL(status.createUrl).searchParams.get("new_app"), "1");
+ assert.equal((await srv.built.slackInstallation.get())?.botToken, "xoxb-own");
+ } finally {
+ await srv.close();
+ }
+});
diff --git a/test/postgres-surface-cache.test.ts b/test/postgres-surface-cache.test.ts
index 346989ccb..eb7a75efb 100644
--- a/test/postgres-surface-cache.test.ts
+++ b/test/postgres-surface-cache.test.ts
@@ -280,3 +280,26 @@ test("pg surface-cache: revisedSince skips self edits and scopes to a thread", {
await cache.close();
}
});
+
+test("pg mirror reads sanitize NUL, retain files and preserve newer text on a handled replay", { skip }, async () => {
+ const cache = createPostgresSurfaceCache(URL!);
+ try {
+ await cache.ingest([
+ {
+ container: "CMIRROR",
+ ts: "1.0",
+ text: "a\0b \\u0000",
+ editedAt: 50,
+ files: [{ fileId: "F1", name: "notes\0.txt" }],
+ },
+ ]);
+ await cache.ingest([{ container: "CMIRROR", ts: "1.0", text: "stale", handled: true }]);
+ const [message] = await cache.readMessages("CMIRROR", { at: "1.0", noFallback: true });
+ assert.equal(message?.text, "ab \\u0000");
+ assert.equal(message?.handled, true);
+ assert.equal(message?.files?.[0]?.name, "notes.txt");
+ assert.deepEqual(await cache.readMessages("CMIRROR", { at: "2.0", noFallback: true }), []);
+ } finally {
+ await cache.close();
+ }
+});
diff --git a/test/slack-history-rate-limit.test.ts b/test/slack-history-rate-limit.test.ts
new file mode 100644
index 000000000..a1f9f4789
--- /dev/null
+++ b/test/slack-history-rate-limit.test.ts
@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { once } from "node:events";
+import { test } from "node:test";
+import { WebClient, LogLevel } from "@slack/web-api";
+import { HISTORY_NO_RETRY } from "../src/slack/config.ts";
+import { slackHistoryRateLimitMessage } from "../src/slack/history-rate-limit.ts";
+
+test("managed history throttling gives retry timing and workspace app setup without leaking the error", () => {
+ const message = slackHistoryRateLimitMessage(
+ { code: "slack_webapi_rate_limited_error", retryAfter: 30, message: "private-token" },
+ { managed: true, setupUrl: "https://qm.example/admin/?setup=slack" },
+ );
+ assert.match(message!, /Retry after 30 seconds/);
+ assert.match(message!, /Earlier context may be incomplete/);
+ assert.match(message!, /workspace admin/);
+ assert.match(message!, /https:\/\/qm.example\/admin\/\?setup=slack/);
+ assert.doesNotMatch(message!, /private-token/);
+});
+
+test("workspace-owned apps receive retry guidance without instructions to replace their app", () => {
+ const message = slackHistoryRateLimitMessage({ code: "slack_webapi_rate_limited_error", retryAfter: 2.2 });
+ assert.match(message!, /Retry after 3 seconds/);
+ assert.doesNotMatch(message!, /set up|workspace-owned/);
+});
+
+test("unrelated errors do not suggest changing Slack apps", () => {
+ for (const error of [null, "rate limited", new Error("429"), { data: { error: "missing_scope" } }]) {
+ assert.equal(slackHistoryRateLimitMessage(error, { managed: true }), undefined);
+ }
+});
+
+test("malformed delay and unsafe setup URLs use plain guidance", () => {
+ for (const setupUrl of ["javascript:alert(1)", "https://user:[email protected]/admin/", "invalid"]) {
+ const message = slackHistoryRateLimitMessage(
+ { data: { error: "ratelimited" }, retryAfter: "invalid" },
+ { managed: true, setupUrl },
+ );
+ assert.match(message!, /Try again shortly/);
+ assert.match(message!, /QM's Slack settings/);
+ assert.doesNotMatch(message!, /javascript|secret|NaN/);
+ }
+});
+
+test("Slack history 429 returns immediately instead of sleeping inside the SDK", { timeout: 5000 }, async () => {
+ let calls = 0;
+ const server = createServer((_req, res) => {
+ calls++;
+ res.writeHead(429, { "retry-after": "60", "content-type": "application/json" });
+ res.end(JSON.stringify({ ok: false, error: "ratelimited" }));
+ });
+ server.listen(0, "127.0.0.1");
+ await once(server, "listening");
+ const address = server.address();
+ assert.ok(address && typeof address === "object");
+ const client = new WebClient("test-token", {
+ ...HISTORY_NO_RETRY,
+ slackApiUrl: `http://127.0.0.1:${address.port}/api/`,
+ logLevel: LogLevel.ERROR,
+ });
+ try {
+ await assert.rejects(client.conversations.history({ channel: "C1" }), (error: unknown) => {
+ assert.match(slackHistoryRateLimitMessage(error)!, /Retry after 60 seconds/);
+ return true;
+ });
+ assert.equal(calls, 1);
+ } finally {
+ server.closeAllConnections();
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ }
+});
diff --git a/test/slack-index.integration.test.ts b/test/slack-index.integration.test.ts
index bdbe7af8b..14b970fe7 100644
--- a/test/slack-index.integration.test.ts
+++ b/test/slack-index.integration.test.ts
@@ -213,7 +213,15 @@ class FakeApp {
mock.module("@slack/bolt", { defaultExport: { App: FakeApp, LogLevel: { INFO: "info" } } });
mock.module("@slack/socket-mode", { namedExports: { SocketModeClient: FakeSocketModeClient } });
-mock.module("@slack/web-api", { namedExports: { WebClient: class {} } });
+mock.module("@slack/web-api", {
+ namedExports: {
+ WebClient: class {
+ get conversations() {
+ return FakeApp.instances.at(-1)!.client.conversations;
+ }
+ },
+ },
+});
const { slackPluginConfigFromEnv, startSlackPlugin } = await import("../src/slack/index.ts");
diff --git a/test/slack-installation-validation.test.ts b/test/slack-installation-validation.test.ts
new file mode 100644
index 000000000..59487ee1f
--- /dev/null
+++ b/test/slack-installation-validation.test.ts
@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { validateSlackInstallation } from "../src/surfaces/slack-installation.ts";
+
+const botToken = "xoxb-test-secret";
+const appToken = "xapp-test-secret";
+
+test("Slack validation explains provider throttling without trying to parse a non-JSON response", async () => {
+ await assert.rejects(
+ validateSlackInstallation(
+ botToken,
+ appToken,
+ async () => new Response("slow down", { status: 429, headers: { "retry-after": "30" } }),
+ ),
+ /in 30 seconds.*existing connection has not changed/,
+ );
+});
+
+test("Slack validation identifies which token needs a scope", async () => {
+ const fetchImpl: typeof fetch = async (input) =>
+ new Response(
+ JSON.stringify(
+ String(input).endsWith("auth.test") ? { ok: true, app_id: "A1" } : { ok: false, error: "missing_scope" },
+ ),
+ );
+ await assert.rejects(
+ validateSlackInstallation(botToken, appToken, fetchImpl),
+ /App-level token needs connections:write/,
+ );
+});
+
+test("Slack validation gives a recoverable bot-token error without revealing credentials", async () => {
+ await assert.rejects(
+ validateSlackInstallation(
+ botToken,
+ appToken,
+ async () => new Response(JSON.stringify({ ok: false, error: "token_revoked" })),
+ ),
+ (error: Error) => {
+ assert.match(error.message, /Bot token was rejected.*current token/);
+ assert.doesNotMatch(error.message, /test-secret/);
+ return true;
+ },
+ );
+});
diff --git a/test/slack-managed.test.ts b/test/slack-managed.test.ts
index 9b1b50227..4cd7ffaaf 100644
--- a/test/slack-managed.test.ts
+++ b/test/slack-managed.test.ts
@@ -171,3 +171,33 @@ test("installation launch restricts redirect origin and hides service credential
});
await assert.rejects(bad.start(), /invalid URL/);
});
+
+test("own-app switch blocks stale managed callbacks until explicit restart", async (t) => {
+ const { request, store } = await fixture(t);
+ await request("installation", installation);
+ await store.set({ botToken: "xoxb-own", appToken: "xapp-own", teamId: "T123", updatedBy: "admin" });
+ const replacement = { ...installation, installId: "late", installedAt: Date.now() + 1000 };
+ assert.equal((await request("installation", replacement)).status, 409);
+ assert.equal(await store.enableManaged(), false);
+ await request("installation", { installId: installation.installId }, "DELETE");
+ assert.equal((await store.get())?.botToken, "xoxb-own");
+ assert.equal((await request("events", { installId: installation.installId, body: event })).status, 409);
+ await store.delete("admin");
+ assert.equal((await request("installation", replacement)).status, 409);
+ assert.equal(await store.enableManaged(), true);
+ assert.equal((await request("installation", replacement)).status, 202);
+});
+
+test("own-app replacement preserves the managed generation watermark across restart", async (t) => {
+ const { request, store } = await fixture(t);
+ const old = { ...installation, teamId: "TOLD", installedAt: 1000 };
+ assert.equal((await request("installation", old)).status, 202);
+ await store.set({ botToken: "xoxb-own", appToken: "xapp-own", teamId: "TNEW", updatedBy: "admin" });
+ assert.equal((await store.get())?.installedAt, 1000);
+ await store.delete("admin");
+ assert.equal(await store.enableManaged(), true);
+ assert.equal((await request("installation", old)).status, 409);
+ const fresh = { ...installation, installId: "fresh", teamId: "TNEW", installedAt: 2000 };
+ assert.equal((await request("installation", fresh)).status, 202);
+ assert.equal((await store.get())?.teamId, "TNEW");
+});
diff --git a/test/slack-mirror-context.test.ts b/test/slack-mirror-context.test.ts
new file mode 100644
index 000000000..3d28ca803
--- /dev/null
+++ b/test/slack-mirror-context.test.ts
@@ -0,0 +1,272 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createMemorySurfaceCache } from "../src/surface-cache/surface-cache.ts";
+import { createSlackHistoryReader } from "../src/slack/history.ts";
+import { createConversationSerializer } from "../src/slack/conversation-view.ts";
+import { renderConversationView } from "../src/slack/conversation.ts";
+import type { SlackCoreClient } from "../src/api/slack-core-client.ts";
+import type { BotIdentity, Directory } from "../src/slack/directory.ts";
+
+const ids = { botUserId: "UBOT", ownBotId: "BBOT" } as BotIdentity;
+const directory = {
+ classifyUserCached: async (id: unknown, user: string) => ({ actor: { displayName: user } }),
+} as unknown as Directory;
+
+function fixture() {
+ const cache = createMemorySurfaceCache();
+ const core = {
+ readSurfaceMessages: cache.readMessages,
+ rememberSurfaceHistory: async (events) => {
+ await cache.ingest(events);
+ },
+ } as SlackCoreClient;
+ const readHistory = createSlackHistoryReader({
+ core,
+ ids,
+ managed: true,
+ setupUrl: "https://qm.test/admin/?setup=slack",
+ });
+ const client = {
+ conversations: {
+ history: async () => {
+ throw new Error("unexpected history read");
+ },
+ replies: async () => {
+ throw new Error("unexpected replies read");
+ },
+ },
+ };
+ return { cache, core, readHistory, client };
+}
+
+test("warm thread context follows reordered edits and deletes with no history requests", async () => {
+ const { cache, readHistory, client } = fixture();
+ await cache.ingest([
+ { container: "C1", ts: "2.000000", sub: "1.000000", text: "reply", authorId: "U2" },
+ { container: "C1", ts: "1.000000", text: "parent", authorId: "U1" },
+ { container: "OTHER", ts: "3.000000", text: "secret" },
+ ]);
+ await cache.ingest([{ container: "C1", ts: "2.000000", text: "edited", editedAt: 10 }]);
+ await cache.ingest([{ container: "C1", ts: "2.000000", text: "stale", handled: true }]);
+ const first = await readHistory(client, "C1", "1.000000");
+ assert.deepEqual(first.raw.map((m) => m.text).sort(), ["edited", "parent"]);
+ assert.match(first.note!, /not a complete/);
+ await cache.ingest([{ container: "C1", ts: "2.000000", deleted: true }]);
+ assert.deepEqual(
+ (await readHistory(client, "C1", "1.000000")).raw.map((m) => m.text),
+ ["parent"],
+ );
+});
+
+test("automatic context renders overheard messages and preserves literal entities and files", async () => {
+ const { cache, readHistory, client } = fixture();
+ await cache.ingest([
+ {
+ container: "C1",
+ ts: "1000.000001",
+ text: "literal &lt;",
+ authorId: "U1",
+ files: [{ fileId: "F1", name: "notes.txt" }],
+ },
+ { container: "C1", ts: "1000.000002", text: "answer", self: true },
+ ]);
+ const serializer = createConversationSerializer({
+ ids,
+ directory,
+ externalParticipantsEnabled: async () => false,
+ readHistory,
+ });
+ const result = await serializer.serializeSlackConversation(
+ client,
+ { kind: "channel", channel: "C1", ts: "1000.000003", rawText: "trigger", userId: "U1", files: [] },
+ { audience: [] },
+ );
+ assert.equal(result.view.messages.find((m) => m.ts === "1000.000001")?.text, "literal &lt;");
+ assert.deepEqual(result.view.messages.find((m) => m.ts === "1000.000001")?.files, ["notes.txt"]);
+ const rendered = renderConversationView(result.view);
+ assert.ok(rendered.overheard.some((m) => m.text.includes("literal &lt;")));
+ assert.match(rendered.header, /stored Slack events/);
+});
+
+test("missing parent falls back once then the returned parent is stored for later turns", async () => {
+ const { cache, readHistory, client } = fixture();
+ await cache.ingest([{ container: "C1", ts: "2.000000", sub: "1.000000", text: "reply" }]);
+ let reads = 0;
+ client.conversations.replies = async () => {
+ reads++;
+ return { messages: [{ ts: "1.000000", text: "parent" }], has_more: true } as never;
+ };
+ assert.match((await readHistory(client, "C1", "1.000000")).note!, /truncated/);
+ await readHistory(client, "C1", "1.000000");
+ assert.equal(reads, 1);
+});
+
+test("partial mirror retains Slack throttling guidance", async () => {
+ const { cache, readHistory, client } = fixture();
+ await cache.ingest([{ container: "C1", ts: "2.000000", sub: "1.000000", text: "reply" }]);
+ client.conversations.replies = async () => {
+ throw { code: "slack_webapi_rate_limited_error", retryAfter: 60 };
+ };
+ const result = await readHistory(client, "C1", "1.000000");
+ assert.equal(result.raw.length, 1);
+ assert.match(result.note!, /60/);
+ assert.match(result.note!, /https:\/\/qm.test\/admin/);
+});
+
+test("external audience is rejected before reading mirror or Slack", async () => {
+ const serializer = createConversationSerializer({
+ ids,
+ directory,
+ externalParticipantsEnabled: async () => false,
+ readHistory: async () => {
+ throw new Error("unauthorized read");
+ },
+ });
+ const result = await serializer.serializeSlackConversation(
+ {},
+ { kind: "channel", channel: "C1", ts: "1", files: [] },
+ { audience: [{ externalId: "U1", isExternalGuest: true }] },
+ );
+ assert.deepEqual(result.view.messages, []);
+});
+
+test("failed reads preserve the triggering event in automatic context", async () => {
+ const serializer = createConversationSerializer({
+ ids,
+ directory,
+ externalParticipantsEnabled: async () => false,
+ readHistory: async () => {
+ throw new Error("storage unavailable");
+ },
+ });
+ const result = await serializer.serializeSlackConversation(
+ {},
+ { kind: "channel", channel: "C1", ts: "1", rawText: "trigger", files: [] },
+ { audience: [] },
+ );
+ assert.equal(result.view.messages[0]?.text, "trigger");
+ assert.match(result.view.contextNote!, /could not be read/);
+});
+
+test("NUL sanitization retains literal backslash-u text and marks stale messages handled", async () => {
+ const { cache } = fixture();
+ await cache.ingest([{ container: "C1", ts: "1", text: "a\0b \\u0000", editedAt: 10 }]);
+ await cache.ingest([{ container: "C1", ts: "1", text: "old", handled: true }]);
+ const [message] = await cache.readMessages("C1");
+ assert.equal(message?.text, "ab \\u0000");
+ assert.equal(message?.handled, true);
+});
+
+test("read_thread, whats_new and mirror search retain coverage notes and container isolation", async () => {
+ const { createSurfaceToolDeps } = await import("../src/core/orchestrator/surface-tools.ts");
+ const { cache } = fixture();
+ await cache.ingest([
+ { container: "C1", ts: "1.000000", text: "match here" },
+ { container: "SECRET", ts: "2.000000", text: "match secret" },
+ ]);
+ const tools = createSurfaceToolDeps({
+ deps: {
+ deliveries: {},
+ surfaceCache: cache,
+ surfaceContext: {
+ pull: async () => ({
+ messages: [{ ts: "2.000000", threadTs: "1.000000", text: "reply" }],
+ note: "partial context",
+ }),
+ },
+ },
+ input: { surface: "slack", surfaceTools: true },
+ actor: { id: "U1" },
+ conversation: { kind: "channel" },
+ defaultDestination: { type: "slack", target: "C1:1.000000" },
+ } as unknown as import("../src/core/orchestrator/surface-tools.ts").SurfaceToolsContext)!;
+ assert.equal((await tools.readThread()).message, "partial context");
+ assert.equal((await tools.whatsNew()).message, "partial context");
+ const search = await tools.search("match", { source: "mirror" });
+ assert.equal(search.source, "cache");
+ assert.deepEqual(
+ search.hits?.map((m) => m.snippet),
+ ["match here"],
+ );
+});
+
+test("backfilled edit timestamps reject older delayed edit events", async () => {
+ const { cache, readHistory, client } = fixture();
+ client.conversations.replies = async () =>
+ ({ messages: [{ ts: "1.000000", text: "latest edit", edited: { ts: "20.000000" } }] }) as never;
+ await readHistory(client, "C1", "1.000000");
+ await cache.ingest([{ container: "C1", ts: "1.000000", text: "delayed old edit", editedAt: 10_000 }]);
+ const [message] = await cache.readMessages("C1");
+ assert.equal(message?.text, "latest edit");
+ assert.equal(message?.editedAt, 20_000);
+ assert.equal((await readHistory(client, "C1", "1.000000")).raw[0]?.text, "latest edit");
+});
+
+test("surface context combines channel coverage and thread rate-limit notes", async () => {
+ const { createSurfaceContextFulfiller } = await import("../src/slack/surface-context.ts");
+ let outcome: any;
+ const fulfiller = createSurfaceContextFulfiller({
+ core: {
+ fulfillContextRequest: async (_id, result) => {
+ outcome = result;
+ },
+ } as SlackCoreClient,
+ directory,
+ serializer: {
+ shapeRecentMessages: async () => [],
+ } as unknown as import("../src/slack/conversation-view.ts").ConversationSerializer,
+ botToken: "test",
+ clientOptions: {},
+ readHistory: async (_client, _channel, thread) => ({
+ raw: [],
+ hasMore: false,
+ note: thread
+ ? "Retry in 60 seconds; setup: https://qm.test/admin/?setup=slack"
+ : "Stored events may be incomplete.",
+ }),
+ });
+ await fulfiller.fulfillSurfaceContext({}, {
+ id: "request",
+ query: { conversationTarget: "C1:1.0" },
+ } as import("../src/api/slack-core-client.ts").SurfaceContextRequest);
+ assert.match(outcome.result.note, /Stored events/);
+ assert.match(outcome.result.note, /60 seconds/);
+ assert.match(outcome.result.note, /setup=slack/);
+});
+
+test("surface context keeps a successful channel page when an empty thread is throttled", async () => {
+ const { createSurfaceContextFulfiller } = await import("../src/slack/surface-context.ts");
+ let outcome: any;
+ const fulfiller = createSurfaceContextFulfiller({
+ core: {
+ fulfillContextRequest: async (_id, result) => {
+ outcome = result;
+ },
+ } as SlackCoreClient,
+ directory,
+ serializer: {
+ shapeRecentMessages: async (_client: unknown, raw: import("../src/slack/payloads.ts").SlackHistoryMessage[]) =>
+ raw.map((m) => ({ ts: m.ts!, text: m.text!, name: "Alice" })),
+ } as unknown as import("../src/slack/conversation-view.ts").ConversationSerializer,
+ botToken: "test",
+ clientOptions: {},
+ historyRateLimitOptions: { managed: true, setupUrl: "https://qm.test/admin/?setup=slack" },
+ readHistory: async (_client, _channel, thread) => {
+ if (thread) throw { code: "slack_webapi_rate_limited_error", retryAfter: 60 };
+ return {
+ raw: [{ ts: "1.0", text: "stored channel message" }],
+ hasMore: false,
+ note: "Stored events may be incomplete.",
+ };
+ },
+ });
+ await fulfiller.fulfillSurfaceContext({}, {
+ id: "request",
+ query: { conversationTarget: "C1:2.0" },
+ } as import("../src/api/slack-core-client.ts").SurfaceContextRequest);
+ assert.equal(outcome.error, undefined);
+ assert.equal(outcome.result.messages[0].text, "stored channel message");
+ assert.match(outcome.result.note, /Stored events/);
+ assert.match(outcome.result.note, /60/);
+ assert.match(outcome.result.note, /setup=slack/);
+});
diff --git a/test/surface-read-tools.test.ts b/test/surface-read-tools.test.ts
index 2191913dd..71a674c90 100644
--- a/test/surface-read-tools.test.ts
+++ b/test/surface-read-tools.test.ts
@@ -25,7 +25,7 @@ function mention(text: string, channel: string, root: string): TurnRequest {
surface: "slack",
actor,
conversation: { kind: "channel", threadRef: `ch:${channel}:${root}`, channelRef: channel, audience: [actor, mate] },
- deliveryTarget: `slack:${channel}:${root}`,
+ deliveryTarget: `${channel}:${root}`,
text,
liveActor: true,
async: true,
@@ -83,21 +83,22 @@ test("whats_new returns POINTERS (counts of new-here + other active threads), ne
}
});
-test("search falls back to a live scan when no cache is wired, returning author+snippet pointers", async () => {
+test("search defaults to the current channel mirror and returns author/snippet pointers without a live pull", async () => {
const built = freshApp();
built.runtime.start();
const root = "C11:1100.1";
- const stop = startFulfiller(built.app, [
- { ts: "1100.2", author: "Bob", text: "the budget doc is in shared/q2.md" },
- { ts: "1100.3", author: "Cat", text: "unrelated chatter" },
+ await built.surfaceCache.ingest([
+ { container: "C11", ts: "1100.2", authorName: "Bob", text: "the budget doc is in shared/q2.md" },
+ { container: "C11", ts: "1100.3", authorName: "Cat", text: "unrelated chatter" },
+ { container: "CSECRET", ts: "1100.4", authorName: "Eve", text: "the secret budget" },
]);
try {
await built.app.turn(mention("!search budget", "C11", "1100.1"));
const reply = await subToolResult(built, root, "search");
- assert.match(reply, /search\(live\) 1 hit/);
+ assert.match(reply, /search\(cache\) 1 hit/);
+ assert.deepEqual(await built.app.pendingContextRequests("slack"), []);
assert.match(reply, /first=Bob:the budget doc/);
} finally {
- await stop();
await built.runtime.stop();
}
});
@@ -226,7 +227,7 @@ test("search/whats_new surface the mirror coverage window end-to-end once the mi
await built.app.ingestSurfaceEvents(
[
{
- container: "slack:C30:3000.1",
+ container: "C30",
ts: "3000.1",
authorId: "U2",
authorName: "Bob",
@@ -241,8 +242,8 @@ test("search/whats_new surface the mirror coverage window end-to-end once the mi
await built.app.turn(mention("!search budget", "C30", "3000.1"));
const searchReply = await subToolResult(built, root, "search");
assert.match(searchReply, /coverage=\d{4}-\d\d-\d\d/, "the search reply carries the mirror coverage floor");
- await built.app.turn(mention("!whats_new", "C30", "3000.1"));
- const wnReply = await subToolResult(built, root, "whats_new");
+ await built.app.turn(mention("!whats_new", "C30", "3000.2"));
+ const wnReply = await subToolResult(built, "C30:3000.2", "whats_new");
assert.match(wnReply, /coverage=\d{4}-\d\d-\d\d/, "whats_new carries the mirror coverage floor");
} finally {
await stop();
@@ -324,3 +325,29 @@ test("set_standing_order writes the channel policy the ambient judge reads (reco
await built.runtime.stop();
}
});
+
+test("successful Slack reads preserve partial-context and rate-limit guidance in model tool results", async () => {
+ const guidance =
+ "Some context is missing. Slack history is rate-limited; retry in 60 seconds or set up your own Slack app at https://qm.test/admin/?setup=slack";
+ const tool = surfaceTool({
+ async readThread() {
+ return { ok: true, messages: [{ text: "available thread context" }], message: guidance };
+ },
+ async whatsNew() {
+ return { ok: true, hereNew: 2, activeSubConversations: 1, message: guidance };
+ },
+ async search() {
+ return { ok: true, hits: [{ snippet: "available search hit" }], source: "cache", message: guidance };
+ },
+ });
+ for (const [action, expected] of [
+ ["read_thread", "available thread context"],
+ ["whats_new", "2 new in this thread"],
+ ["search", "available search hit"],
+ ]) {
+ const result = await tool.execute(`partial-${action}`, { action, query: "available" });
+ const output = result.content.map((item: { text?: string }) => item.text ?? "").join("\n");
+ assert.ok(output.includes(expected!), action);
+ assert.ok(output.includes(guidance), action);
+ }
+});