feat(agent): route a Slack event to the run that owns the channel

.env.example

@@ -57,6 +57,25 @@ GOOGLE_CLIENT_SECRET=""
 # SLACK_CLIENT_ID=""
 # SLACK_CLIENT_SECRET=""
 
+# Optional, and required only for inbound Slack. It is the Signing Secret on the
+# Slack app's Basic Information page, not a token. Without it the events
+# endpoint refuses every request, which is the safe way round: that endpoint is
+# a public POST, so the signature is the only thing between a stranger and
+# resuming somebody's agent run.
+#
+# Point the Slack app's Event Subscriptions request URL at
+# API_URL + /webhooks/slack/events
+# SLACK_SIGNING_SECRET=""
+
+# Optional, and for local development only. The hostname `bun run tunnel:slack`
+# gives your machine, on a domain in your own Cloudflare account. A named tunnel
+# keeps the same hostname across restarts, so Slack's request URL is set once
+# and never again; the quick `cloudflared --url` tunnel invents a new hostname
+# every time and Slack silently stops delivering.
+#
+# Nothing reads this at runtime. The script reads it, and Slack remembers it.
+# SLACK_TUNNEL_HOSTNAME="crm-dev.example.com"
+
 # Which Entra tenant may sign in. "common" (the default) accepts any work,
 # school or personal Microsoft account and leans on ALLOWED_SIGN_IN to decide
 # who actually gets in; your own tenant's GUID refuses everyone else at

apps/agent/agent/channels/crm.ts

@@ -30,6 +30,7 @@ import { DISPATCH } from "../lib/dispatch-config";
 import { settle } from "../lib/enrichment";
 import { finishRun, runResultOf } from "../lib/run-runtime";
 import { attribute } from "../lib/session-purpose";
+import { drainSlackEvents } from "../lib/slack-events";
 import { createSlackChannel } from "../lib/slack-membership";
 import { reconcileStaleTasks } from "../lib/stale-tasks";
 import { completeTask, taskSubject } from "../lib/tasks";
@@ -146,6 +147,7 @@ export default defineChannel({
 						}),
 					);
 					await drainAgentRuns(send);
+					await drainSlackEvents(send);
 				})(),
 			);
 

apps/agent/agent/lib/agent-actions.ts

@@ -1,12 +1,15 @@
 import {
 	AGENT_ACTION_TYPES,
 	type AgentActionType,
+	SLACK_WORKSPACE_RESOURCE_ID,
 } from "@crm/validation/agent-manifest";
 
 export const AGENT_ACTION_EXECUTORS = {
 	[AGENT_ACTION_TYPES.CRM_ACTIVITY_CREATE]: "create_crm_activity",
 	[AGENT_ACTION_TYPES.RUN_SUMMARY]: "finish_run",
 	[AGENT_ACTION_TYPES.SLACK_MESSAGE_POST]: "post_slack_message",
+	[AGENT_ACTION_TYPES.SLACK_CHANNEL_OPEN]: "open_slack_channel",
+	[AGENT_ACTION_TYPES.SLACK_CHANNEL_INVITE]: "invite_to_slack_channel",
 } as const satisfies Record<AgentActionType, string>;
 
 export function isAgentActionType(value: string): value is AgentActionType {
@@ -22,15 +25,19 @@ export type AgentActionDependency = {
 	readonly fix: string;
 };
 
+const SLACK_DEPENDENCY = {
+	id: "slack",
+	label: "Slack",
+	resourceId: SLACK_WORKSPACE_RESOURCE_ID,
+	fix: "Connect Slack in Settings → Connections.",
+} as const satisfies AgentActionDependency;
+
 export const AGENT_ACTION_DEPENDENCIES = {
 	[AGENT_ACTION_TYPES.CRM_ACTIVITY_CREATE]: null,
 	[AGENT_ACTION_TYPES.RUN_SUMMARY]: null,
-	[AGENT_ACTION_TYPES.SLACK_MESSAGE_POST]: {
-		id: "slack",
-		label: "Slack",
-		resourceId: "slack:workspace",
-		fix: "Connect Slack in Settings → Connections.",
-	},
+	[AGENT_ACTION_TYPES.SLACK_MESSAGE_POST]: SLACK_DEPENDENCY,
+	[AGENT_ACTION_TYPES.SLACK_CHANNEL_OPEN]: SLACK_DEPENDENCY,
+	[AGENT_ACTION_TYPES.SLACK_CHANNEL_INVITE]: SLACK_DEPENDENCY,
 } as const satisfies Record<AgentActionType, AgentActionDependency | null>;
 
 export function actionDependency(

apps/agent/agent/lib/builder-runtime.ts

@@ -9,6 +9,7 @@ import { readAgentModel } from "@crm/db/settings";
 import { WORKSPACE_ID } from "@crm/db/workspace";
 import { AGENT_ACTION_TYPES } from "@crm/validation/agent-manifest";
 import { z } from "zod";
+import type { DraftAction } from "../subagents/agent_builder/lib/draft-input";
 import { actionDependency } from "./agent-actions";
 import { requestStaleSlackInventorySync } from "./slack-people";
 
@@ -43,29 +44,7 @@ export type DraftTrigger = {
 	intervalMinutes?: number | null;
 };
 
-export type DraftAction =
-	| {
-			type: typeof AGENT_ACTION_TYPES.CRM_ACTIVITY_CREATE;
-			provider: "crm";
-			summary: string;
-			activityTypes: ("NOTE" | "TASK")[];
-	  }
-	| {
-			type: typeof AGENT_ACTION_TYPES.RUN_SUMMARY;
-			provider: "crm";
-			summary: string;
-	  }
-	| {
-			type: typeof AGENT_ACTION_TYPES.SLACK_MESSAGE_POST;
-			provider: "slack";
-			summary: string;
-			destination: {
-				kind: "channel" | "user";
-				resolution: "chosen";
-				id: string;
-				label: string;
-			};
-	  };
+export type { DraftAction };
 
 export type DraftAgentInput = {
 	name: string;

apps/agent/agent/lib/run-resume.ts

@@ -0,0 +1,130 @@
+import { db } from "@crm/db";
+import type { SendFn } from "eve/channels";
+import { APP_AUTH } from "./app-auth";
+import { runToken } from "./custom-agent-dispatch";
+
+const LIVE_STATUSES = ["QUEUED", "RUNNING", "WAITING_FOR_APPROVAL"] as const;
+
+export type ResumeOutcome =
+	| { kind: "resumed"; runId: string; sessionId: string }
+	| { kind: "ignored"; runId: string; reason: string };
+
+export type ResumeInput = {
+	runId: string;
+	message: string;
+	source: string;
+	attributes?: Readonly<Record<string, string>>;
+};
+
+export async function resumeAgentRun(
+	input: ResumeInput,
+	send: SendFn,
+): Promise<ResumeOutcome> {
+	const { runId, message, source } = input;
+
+	const run = await db.agentRun.findUnique({
+		where: { id: runId },
+		select: {
+			id: true,
+			status: true,
+			sessionId: true,
+			agentId: true,
+			versionId: true,
+			agent: { select: { status: true, name: true } },
+		},
+	});
+
+	if (!run) return { kind: "ignored", runId, reason: "no such run" };
+
+	if (!(LIVE_STATUSES as readonly string[]).includes(run.status)) {
+		return {
+			kind: "ignored",
+			runId,
+			reason: `the run is ${run.status.toLowerCase()}`,
+		};
+	}
+
+	if (run.agent.status !== "LIVE") {
+		return {
+			kind: "ignored",
+			runId,
+			reason: `the agent is ${run.agent.status.toLowerCase()}`,
+		};
+	}
+
+	if (!run.sessionId) {
+		return {
+			kind: "ignored",
+			runId,
+			reason: "the run has not started a session yet",
+		};
+	}
+
+	try {
+		const session = await send(message, {
+			auth: {
+				authenticator: APP_AUTH.authenticator,
+				principalType: APP_AUTH.principalType,
+				principalId: APP_AUTH.principalId,
+				attributes: {
+					purpose: "team-agent",
+					runId: run.id,
+					agentId: run.agentId,
+					versionId: run.versionId,
+					resumeSource: source,
+					...input.attributes,
+				},
+			},
+			continuationToken: runToken(run.id),
+			title: `${run.agent.name} run`,
+			mode: "task",
+		});
+
+		return { kind: "resumed", runId, sessionId: session.id };
+	} catch (error) {
+		return {
+			kind: "ignored",
+			runId,
+			reason: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+export async function runOnSlackChannel(
+	channelId: string,
+): Promise<string | null> {
+	const trimmed = channelId.trim();
+	if (!trimmed) return null;
+
+	const run = await db.agentRun.findFirst({
+		where: {
+			slackChannelId: trimmed,
+			status: { in: [...LIVE_STATUSES] },
+		},
+		orderBy: { createdAt: "desc" },
+		select: { id: true },
+	});
+
+	return run?.id ?? null;
+}
+
+export async function channelOfRun(runId: string): Promise<string | null> {
+	const run = await db.agentRun.findUnique({
+		where: { id: runId },
+		select: { slackChannelId: true },
+	});
+
+	return run?.slackChannelId ?? null;
+}
+
+export async function claimSlackChannel(
+	runId: string,
+	channelId: string,
+): Promise<string | null> {
+	await db.agentRun.updateMany({
+		where: { id: runId, slackChannelId: null },
+		data: { slackChannelId: channelId.trim() },
+	});
+
+	return channelOfRun(runId);
+}