nanocoai/nanoclaw / .claude/skills/slack-agent-flow
slack-agent-flow
FlaggedLet an existing Slack agent create new agents that arrive as their own Slack bots — provisioned app, operator DM, and a shared three-way room, hot-started without a host restart.
src/modules/slack-agent-flow/orchestrate.ts
View on GitHub/**
* The Slack leg of create_agent — steps S1–S13 (one typed step id each).
*
* Ordering is load-bearing:
* - S1/S2 are local/cheap prechecks — nothing external is created until the
* operator identity and the origin bot token both resolve.
* - S10 (SLACK_A2A_ROOMS append) runs strictly BEFORE the origin agent is
* nudged to post the room intro, so every sibling instance's a2a
* bridge admits the bot-authored intro instead of dropping it as a bot
* sender.
* - S13's DM intro and the origin intro nudge are gated on rows newly
* created in S8/S11 — a retry (finish script) never double-posts or
* double-nudges.
* Every step is idempotent: provision reuses .env tokens, messaging groups
* and wirings are get-before-create, conversations.open is idempotent on
* Slack's side.
*
* Slack HTTP plumbing comes from the shared channel-layer lib
* (src/channels/slack-lib.ts, installed with the Slack channel payload);
* access to the skill-installed adapter modules goes through
* loadSlackChannelDeps() so a partial install fails as a typed step error.
*/
import {
resolveUnknownSenderPolicy,
resolveWiringDefaults,
validateEngageAgainstChannel,
} from '../../channels/channel-defaults.js';
import {
SlackApiError,
botTokenKeyForInstance,
slackAuthTest,
slackConversationsOpen,
slackPostMessage,
} from '../../channels/slack-lib.js';
import { projectDestinationsToSessions } from '../../cli/resources/destinations.js';
import { getAgentGroup } from '../../db/agent-groups.js';
import {
createMessagingGroup,
createMessagingGroupAgent,
getAllMessagingGroups,
getMessagingGroup,
getMessagingGroupAgentByPair,
getMessagingGroupAgents,
getMessagingGroupByPlatform,
} from '../../db/messaging-groups.js';
import { log } from '../../log.js';
import { templateDescription } from '../../templates/library.js';
import type { MessagingGroup, MessagingGroupAgent, Session } from '../../types.js';
import {
createDestination,
getDestinationByName,
getDestinationByTarget,
normalizeName,
} from '../agent-to-agent/db/agent-destinations.js';
import { notifyAgent, pickApprover } from '../approvals/primitive.js';
import { appendToEnvList, readEnvValue } from './env-file.js';
import { provisionSlackApp } from './provision.js';
import { createRoomCanvas, wireCanvasComments } from './room-canvas.js';
import { assertSlackInstancesModuleInstalled, loadSlackChannelDeps } from './slack-deps.js';
import { SlackFlowError, type OrchestrateSuccess, type SlackFlowStep } from './types.js';
function generateId(prefix: string): string {
return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
}
function envSuffix(slug: string): string {
return slug.toUpperCase().replace(/-/g, '_');
}
/** Wrap a non-typed failure with the step it happened in. Never carries token
* values. A SlackApiError keeps its own step — the shared Slack lib
* (src/channels/slack-lib.ts) tags each call with the flow step id the call
* site passed, which is more precise than the enclosing wrapper's step. */
function asFlowError(err: unknown, step: SlackFlowStep): SlackFlowError {
if (err instanceof SlackFlowError) return err;
if (err instanceof SlackApiError) return new SlackFlowError(err.step as SlackFlowStep, err.message);
return new SlackFlowError(step, err instanceof Error ? err.message : String(err));
}
/** One canonical slugger — the same normalizeName the a2a destination namespace uses. */
export function deriveInstanceSlug(name: string): string {
return normalizeName(name);
}
/**
* First approver with a Slack identity, 'slack:' prefix stripped. pickApprover
* order (scoped admins → global admins → owners) picks who gets the DM.
*/
export async function resolveOperatorSlackUserId(sourceAgentGroupId: string): Promise<string | null> {
const hit = (await pickApprover(sourceAgentGroupId)).find((id) => /^slack:U/i.test(id));
return hit ? hit.slice('slack:'.length) : null;
}
/**
* A slug conflicts when its .env footprint is already claimed (token key set
* or slug listed in SLACK_INSTANCES) AND its `slack-<slug>` instance is wired
* to a DIFFERENT agent group. Claimed-but-wired-to-this-group (or to nothing)
* is the retry path — reuse.
*/
async function slugConflicts(slug: string, newAgentGroupId: string, rootDir: string): Promise<boolean> {
const tokenExists = readEnvValue(rootDir, `SLACK_BOT_TOKEN_${envSuffix(slug)}`) !== undefined;
const instances = (readEnvValue(rootDir, 'SLACK_INSTANCES') ?? '')
.split(',')
.map((s) => s.trim())
.filter(Boolean);
if (!tokenExists && !instances.includes(slug)) return false;
const instanceKey = `slack-${slug}`;
for (const mg of await getAllMessagingGroups()) {
if (mg.instance !== instanceKey) continue;
for (const wiring of await getMessagingGroupAgents(mg.id)) {
if (wiring.agent_group_id !== newAgentGroupId) return true;
}
}
return false;
}
export async function dedupeSlug(
base: string,
newAgentGroupId: string,
rootDir: string = process.cwd(),
): Promise<string> {
let slug = base;
for (let n = 2; await slugConflicts(slug, newAgentGroupId, rootDir); n++) slug = `${base}-${n}`;
return slug;
}
async function ensureMessagingGroupRow(spec: {
platformId: string;
instance: string;
name: string;
isGroup: boolean;
unknownSenderPolicy: MessagingGroup['unknown_sender_policy'];
}): Promise<{ mg: MessagingGroup; created: boolean }> {
const existing = await getMessagingGroupByPlatform('slack', spec.platformId, spec.instance);
if (existing) return { mg: existing, created: false };
const mg: MessagingGroup = {
id: generateId('mg'),
channel_type: 'slack',
platform_id: spec.platformId,
instance: spec.instance,
name: spec.name,
is_group: spec.isGroup ? 1 : 0,
unknown_sender_policy: spec.unknownSenderPolicy,
created_at: new Date().toISOString(),
};
await createMessagingGroup(mg);
return { mg, created: true };
}
/** Flow-chosen deviations from the channel-declared wiring defaults. */
interface WiringOverrides {
/** Set together with engage_pattern to bypass resolveWiringDefaults. */
engage_mode?: MessagingGroupAgent['engage_mode'];
engage_pattern?: string | null;
ignored_message_policy?: MessagingGroupAgent['ignored_message_policy'];
session_mode?: MessagingGroupAgent['session_mode'];
/** 1/0 explicit stamp; null = explicitly leave the column NULL (inherit the
* channel declaration at fanout time); omitted = follow the derived
* creation-time stamp (resolveWiringDefaults stamps threads=1 when the
* declared sessionMode is 'per-thread', else null). */
threads?: number | null;
}
/** Get-before-create wiring with channel-declared defaults (engage fields,
* plus the B7 session-mode/threads creation-time stamps) unless overridden.
* True iff newly created. */
async function ensureWiring(
mg: MessagingGroup,
agentGroupId: string,
agentGroupName: string,
overrides: WiringOverrides = {},
): Promise<boolean> {
if (await getMessagingGroupAgentByPair(mg.id, agentGroupId)) return false;
const channelKey = mg.instance ?? mg.channel_type;
// Overriding engage_mode bypasses the declaration entirely (flow-owned
// room semantics, D4); declaration-resolved wirings take the declared
// session_mode / threads stamps too (B7).
const resolved =
overrides.engage_mode !== undefined
? undefined
: resolveWiringDefaults(channelKey, mg.is_group === 1, agentGroupName, mg.channel_type);
const engage = resolved ?? { engage_mode: overrides.engage_mode!, engage_pattern: overrides.engage_pattern ?? null };
const threads = overrides.threads !== undefined ? overrides.threads : (resolved?.threads ?? null);
const wiring: MessagingGroupAgent = {
id: generateId('mga'),
messaging_group_id: mg.id,
agent_group_id: agentGroupId,
engage_mode: engage.engage_mode,
engage_pattern: engage.engage_pattern,
sender_scope: 'all',
ignored_message_policy: overrides.ignored_message_policy ?? 'drop',
session_mode: overrides.session_mode ?? resolved?.session_mode ?? 'shared',
priority: 0,
...(threads !== null ? { threads } : {}),
created_at: new Date().toISOString(),
};
validateEngageAgainstChannel(wiring, mg);
// createMessagingGroupAgent persists an explicit `threads` value itself
// (follow-up UPDATE in src/db/messaging-groups.ts) — the declared threads:1 stamp lands.
await createMessagingGroupAgent(wiring);
return true;
}
/**
* Room-wiring semantics for flow-created rooms (D4): each bot speaks only
* when @-mentioned; everything else accumulates as ambient context delivered
* with the next mention. Deliberately NOT the channel group default —
* flow-created rooms only.
*/
const ROOM_WIRING_OVERRIDES: WiringOverrides = {
engage_mode: 'mention',
engage_pattern: null,
ignored_message_policy: 'accumulate',
};
/** One bot in a shared room: its adapter instance and the agent group behind it. */
export interface RoomParticipant {
/** Adapter-instance key ('slack' or 'slack-<slug>'). */
instanceKey: string;
botUserId: string;
agentGroupId: string;
agentGroupName: string;
}
/**
* Idempotent agent→agent destination (= ACL grant + local name). No-op when
* a destination for the target already exists under any name (upstream
* create_agent's parent/child rows count). Name collisions get a numeric
* suffix, mirroring ensureAgentDestinationForWiring.
*/
async function ensureAgentDestination(fromGroupId: string, toGroupId: string, toName: string): Promise<void> {
if (fromGroupId === toGroupId) return;
if (await getDestinationByTarget(fromGroupId, 'agent', toGroupId)) return;
const base = normalizeName(toName) || toGroupId.slice(0, 8);
let localName = base;
let suffix = 2;
while (await getDestinationByName(fromGroupId, localName)) {
localName = `${base}-${suffix}`;
suffix++;
}
await createDestination({
agent_group_id: fromGroupId,
local_name: localName,
target_type: 'agent',
target_id: toGroupId,
created_at: new Date().toISOString(),
});
}
/** Full pairwise a2a destination symmetry between every distinct agent group
* in the room — "ask Devin" must be actionable from any participant. */
async function ensurePairwiseAgentDestinations(participants: RoomParticipant[]): Promise<void> {
for (const a of participants) {
for (const b of participants) {
if (a.agentGroupId === b.agentGroupId) continue;
await ensureAgentDestination(a.agentGroupId, b.agentGroupId, b.agentGroupName);
}
}
}
/**
* Public purpose: ONLY the explicitly provided line (capped 80). No fallback
* from the instructions — the creation prompt is the agent's private persona
* and never appears on shared surfaces. No purpose = the intro simply
* doesn't state one.
*/
export function publicPurpose(explicit: string | undefined): string | undefined {
const cleaned = explicit?.trim();
if (!cleaned) return undefined;
return cleaned.length <= 80 ? cleaned : `${cleaned.slice(0, 80)}…`;
}
/**
* The ORIGIN agent — not a host template — introduces the new agent
* in the shared room. This is the instruction the origin session wakes to;
* the intro itself stays in the agent's own voice, and the room-contract
* data (purpose, members, created date) lives on the canvas, not in chat.
*/
function roomIntroNudgeText(args: {
newAgentName: string;
newBotUserId: string;
roomName: string;
/** The origin agent's local destination name for the room. */
roomDestination: string;
purpose?: string;
}): string {
return (
`A shared Slack room "${args.roomName}" was just opened with you, the operator, and your new agent ${args.newAgentName}` +
`${args.purpose ? ` (${args.purpose})` : ''}. ` +
`Post a brief introduction of ${args.newAgentName} there now via send_message({ to: "${args.roomDestination}", ... }): ` +
`1-2 lines in your own voice saying what they're for, tagging them with <@${args.newBotUserId}> ` +
`(include that literally — it renders as a mention). Just the intro — no mechanics, no member lists.`
);
}
/**
* N-bot-capable room step (S9–S13's room half): open the MPIM as `creator`
* with the operator + every participating bot, allowlist it for a2a, create
* one mg row + mention/accumulate wiring PER participating instance, ensure
* pairwise a2a destinations, then (only when rows were newly created) create
* the room canvas — the room's pinned contract surface (no contract
* message, no link post; the channel canvas is already the room's canvas
* tab) — and wire its comment shadow channel for every participant. The
* conversational create_agent flow calls this with the 3-way default; any
* caller may pass a larger participant list.
*/
export async function ensureAgentRoom(args: {
/** Bot that opens the MPIM and creates the canvas. Must be one of `participants`. */
creator: RoomParticipant;
creatorBotToken: string;
operatorUserId: string;
/** All bots in the room, creator included. */
participants: RoomParticipant[];
/** Additional member user ids beyond the operator + participating bots —
* e.g. Slack-UI-added humans carried over when add_to_room forks a room.
* Members only; they get no mg rows or wirings. */
extraMemberUserIds?: string[];
roomName: string;
/** Creation prompt (room purpose) — the canvas contract excerpt. */
purpose?: string;
rootDir: string;
}): Promise<{ roomChannelId: string; created: boolean }> {
const { creator, creatorBotToken, operatorUserId, participants, rootDir } = args;
// S9 mpim-open — operator + carried extra members + every other
// participating bot, opened AS the creator.
const otherBotIds = participants.filter((p) => p.botUserId !== creator.botUserId).map((p) => p.botUserId);
const roomChannelId = await slackConversationsOpen(
creatorBotToken,
[operatorUserId, ...(args.extraMemberUserIds ?? []), ...otherBotIds],
'mpim-open',
);
// S10 a2a-env — strictly before the origin agent can be nudged to post its
// intro: every sibling instance's a2a bridge must already allow the room
// or it drops bot-authored posts.
try {
appendToEnvList(rootDir, 'SLACK_A2A_ROOMS', roomChannelId);
} catch (err) {
throw asFlowError(err, 'a2a-env');
}
// S11 room-wire — one row PER participating instance (router lookup is
// exact-on-instance). unknown_sender_policy 'public' explicitly: sibling
// bridges' access gates must never approval-spam admitted bot messages.
// Wirings are mention/accumulate (D4 — flow-created rooms only).
let created = false;
try {
for (const p of participants) {
const row = await ensureMessagingGroupRow({
platformId: `slack:${roomChannelId}`,
instance: p.instanceKey,
name: args.roomName,
isGroup: true,
unknownSenderPolicy: 'public',
});
await ensureWiring(row.mg, p.agentGroupId, p.agentGroupName, ROOM_WIRING_OVERRIDES);
created = row.created || created;
}
await ensurePairwiseAgentDestinations(participants);
} catch (err) {
throw asFlowError(err, 'room-wire');
}
// S12 projections — in-host-process, so already-running containers see the
// auto-created destinations without waiting for the next spawn.
for (const groupId of new Set(participants.map((p) => p.agentGroupId))) {
await projectDestinationsToSessions(groupId);
}
// S13 room half — gated on newly created rows so a retry never grows a
// second canvas. No room-contract message: the canvas tab is the
// pinned surface and carries the contract data; the intro is authored by
// the ORIGIN agent (nudged by runFlow). Canvas failure is non-fatal
// (C2: createRoomCanvas never throws) — no canvas, no shadow channel.
if (created) {
const canvasId = await createRoomCanvas(creatorBotToken, roomChannelId, {
roomName: args.roomName,
purpose: args.purpose ?? args.roomName,
creatorUserId: operatorUserId,
agentNames: participants.map((p) => p.agentGroupName),
});
// Canvas comments arrive in a Slackbot-owned shadow channel (canvas id
// with F→C) — wire EVERY participating instance: creator as the
// pattern-engage default responder, siblings mention/accumulate.
// Non-throwing; no canvas id, nothing to wire.
if (canvasId) await wireCanvasComments(canvasId, creator, participants, args.roomName);
}
return { roomChannelId, created };
}
/**
* How long the flow waits inline for a workspace install approval, and how
* often it checks. The default is five minutes at a five-second cadence —
* long enough for someone already at their desk, short enough that the app
* parks (and stays resumable) rather than holding this session's delivery
* open indefinitely.
*
* `SLACK_INSTALL_WAIT_MS=0` skips the wait entirely: installs that always go
* through a slow approval queue are better served by parking immediately and
* finishing on a later ask. `SLACK_INSTALL_POLL_MS` moves the cadence.
*/
function resolveInstallWait(rootDir: string): { intervalMs?: number; timeoutMs?: number } | undefined {
const num = (key: string): number | undefined => {
const raw = readEnvValue(rootDir, key);
if (raw === undefined) return undefined;
const parsed = Number(raw);
return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
};
const timeoutMs = num('SLACK_INSTALL_WAIT_MS');
const intervalMs = num('SLACK_INSTALL_POLL_MS');
if (timeoutMs === undefined && intervalMs === undefined) return undefined;
return { ...(timeoutMs !== undefined ? { timeoutMs } : {}), ...(intervalMs !== undefined ? { intervalMs } : {}) };
}
/**
* The one line the human gets while the flow waits on a workspace install
* approval. Short on purpose: the link is the only actionable part, and the
* flow says nothing else until it either finishes or parks.
*/
export function installPendingText(displayName: string, info: { installUrl?: string; resumed: boolean }): string {
const where = info.installUrl ? ` Approve it here: ${info.installUrl}` : '';
return info.resumed
? `Still waiting on your workspace to approve installing ${displayName}.${where} — I'll finish setting it up as soon as that lands.`
: `${displayName} is created, but your workspace needs an admin to approve installing it.${where} — I'll finish the setup automatically once it's approved.`;
}
interface FlowArgs {
slug: string;
displayName: string;
sourceGroupId: string;
newAgentGroupId: string;
originInstanceKey: string;
/** Slack channel the create was asked for in — where the flow talks back
* while it waits. Absent on the out-of-process finish path, which prints
* to the operator's terminal instead. */
originChannelId?: string;
rootDir: string;
/** false on the out-of-process finish path — S5 needs the live host's registry. */
hotStart: boolean;
/** Agent instructions excerpt — drives the broker-generated avatar. */
description?: string;
/** Template the agent was built from; recorded with the broker as attribution. */
template?: string;
/** Short PUBLIC line for the room contract + canvas ("what this agent is
* for"). Falls back to a first-sentence excerpt of the instructions —
* never the full creation prompt (it may carry private detail). */
purpose?: string;
/** true → plain manifest variant (guest-visible); false/absent → agent_view. */
allowGuests?: boolean;
/** The session whose create_agent call started the flow — receives the
* room-intro nudge. Absent on the out-of-process finish path. */
originSession?: Session;
/**
* Room policy: 'own' (default) opens the shared origin+operator
* room; 'none' skips the room half entirely — the multi-create pattern is
* N creates with room:'none' followed by one create_room with all of them.
*/
room?: 'own' | 'none';
/** Wait budget for a deferred workspace install. Tests shorten it. */
installWait?: { intervalMs?: number; timeoutMs?: number };
/** Extra sink for the pending-install line — the finish script prints it to
* the operator's terminal, which has no Slack conversation to post into. */
onInstallPending?: (text: string) => void;
}
async function runFlow(args: FlowArgs): Promise<OrchestrateSuccess> {
const { slug, displayName, sourceGroupId, newAgentGroupId, originInstanceKey, rootDir } = args;
const instanceKey = `slack-${slug}`;
// S1 operator-identity
const operatorUserId = await resolveOperatorSlackUserId(sourceGroupId);
if (!operatorUserId) {
throw new SlackFlowError(
'operator-identity',
'no approver with a Slack identity (slack:U…) found in user_roles — grant one with `ncl roles grant` and retry',
);
}
// S2 origin-auth — prove the origin instance's token before provisioning anything.
const originTokenKey = botTokenKeyForInstance(originInstanceKey);
const originBotToken = readEnvValue(rootDir, originTokenKey);
if (!originBotToken) {
throw new SlackFlowError(
'origin-auth',
`missing ${originTokenKey} in .env for origin instance '${originInstanceKey}'`,
);
}
const originAuth = await slackAuthTest(originBotToken, 'origin-auth');
const originBotUserId = originAuth.userId;
// S3/S4 provision. A workspace that requires an admin to approve installs
// refuses auto-install, and provisionSlackApp then waits for the human to
// finish it in the browser. That wait is silent from the outside, so it
// announces itself HERE, as the origin bot, in the conversation the create
// was asked for — the origin agent cannot relay it, since its own replies
// cannot be delivered while this handler is still running. A failed
// announcement is not worth abandoning the wait for.
const app = await provisionSlackApp({
slug,
displayName,
rootDir,
teamId: originAuth.teamId,
description: args.description,
allowGuests: args.allowGuests,
requestedBy: operatorUserId,
template: args.template,
installWait: args.installWait ?? resolveInstallWait(rootDir),
onInstallPending: async (info) => {
const text = installPendingText(displayName, info);
log.info('Waiting on a Slack workspace install approval', { step: 'install-wait', appId: info.appId });
args.onInstallPending?.(text);
if (!args.originChannelId) return;
try {
await slackPostMessage(originBotToken, args.originChannelId, text, 'install-wait');
} catch (err) {
log.warn('Could not announce the pending Slack install', {
step: 'install-wait',
err: err instanceof Error ? err.message : String(err),
});
}
},
});
// S5 adapter-start. The multi-instance module must be installed regardless
// of hotStart: S6-S8 below wire DB rows to an instance name the runtime
// needs to be able to start after a restart, so the out-of-process finish
// path (hotStart: false) checks this too instead of silently skipping
// straight to DB writes for an instance nothing can ever connect.
await assertSlackInstancesModuleInstalled();
if (args.hotStart) {
// Hot-add the new instance into the live registry.
const deps = await loadSlackChannelDeps();
deps.registerChannelAdapter(instanceKey, {
factory: () => deps.slackInstanceBridgeFactory(slug),
defaults: deps.SLACK_DEFAULTS,
});
let started: 'started' | 'already-active' | 'no-credentials';
try {
started = await deps.startChannelAdapter(instanceKey);
} catch (err) {
throw asFlowError(err, 'adapter-start');
}
// 'already-active' is the retry path — the instance survived a previous attempt.
if (started === 'no-credentials') {
throw new SlackFlowError(
'adapter-start',
`adapter '${instanceKey}' found no credentials in .env (SLACK_BOT_TOKEN_${app.envSuffix} / SLACK_APP_TOKEN_${app.envSuffix})`,
);
}
}
// S6 new-bot identity (auth.test gates the DM open — same step id).
const newBotUserId = (await slackAuthTest(app.botToken, 'dm-open')).userId;
// S7 dm-open — the operator DM, opened AS the new bot.
const dmChannelId = await slackConversationsOpen(app.botToken, [operatorUserId], 'dm-open');
// S8 dm-wire. Agent-view apps (the default variant, allowGuests !== true)
// get thread-per-conversation DMs from the CHANNEL DECLARATION: the
// Slack adapter's SLACK_DEFAULTS declares dm.sessionMode 'per-thread',
// resolveWiringDefaults derives the threads=1 stamp from it (per-thread
// sessions structurally require honored thread ids), and ensureWiring
// stamps whatever it resolves — nothing is hardcoded here. The plain
// (allow_guests) variant has no agent-mode DM surface, so it pins
// session_mode 'shared' and leaves the threads column NULL explicitly.
let dmCreated = false;
try {
const dmRow = await ensureMessagingGroupRow({
platformId: `slack:${dmChannelId}`,
instance: instanceKey,
name: `${displayName} DM`,
isGroup: false,
unknownSenderPolicy: resolveUnknownSenderPolicy(instanceKey, false, 'slack'),
});
dmCreated = dmRow.created;
const agentView = args.allowGuests !== true;
await ensureWiring(
dmRow.mg,
newAgentGroupId,
displayName,
agentView ? {} : { session_mode: 'shared', threads: null },
);
} catch (err) {
throw asFlowError(err, 'dm-wire');
}
// S9–S13 room half: MPIM + allowlist + per-instance mention/accumulate
// wirings + pairwise destinations + canvas + room-contract intro. The
// conversational flow's 3-way default; ensureAgentRoom itself is N-capable.
// room:'none' skips the whole half — the DM is the entire surface
// and the caller composes a shared room later via create_room.
let roomChannelId: string | undefined;
if (args.room !== 'none') {
const sourceGroupName = (await getAgentGroup(sourceGroupId))?.name ?? sourceGroupId;
const newParticipant: RoomParticipant = {
instanceKey,
botUserId: newBotUserId,
agentGroupId: newAgentGroupId,
agentGroupName: displayName,
};
const roomName = `${displayName} room`;
const roomPurpose = publicPurpose(args.purpose);
const room = await ensureAgentRoom({
creator: newParticipant,
creatorBotToken: app.botToken,
operatorUserId,
participants: [
{
instanceKey: originInstanceKey,
botUserId: originBotUserId,
agentGroupId: sourceGroupId,
agentGroupName: sourceGroupName,
},
newParticipant,
],
roomName,
purpose: roomPurpose,
rootDir,
});
roomChannelId = room.roomChannelId;
// The ORIGIN agent authors the room intro — an instruction-shaped
// system nudge (trigger=1 wake via notifyAgent) into the origin session,
// gated on the S13 created-gate so a flow retry never double-nudges. The
// wizard first-agent path never reaches here (it opens no room); the
// out-of-process finish path has no origin session to nudge. The room
// destination was projected into the live session in S12.
if (room.created && args.originSession) {
const roomMg = await getMessagingGroupByPlatform('slack', `slack:${roomChannelId}`, originInstanceKey);
const roomDest = roomMg ? await getDestinationByTarget(sourceGroupId, 'channel', roomMg.id) : undefined;
await notifyAgent(
args.originSession,
roomIntroNudgeText({
newAgentName: displayName,
newBotUserId,
roomName,
roomDestination: roomDest?.local_name ?? normalizeName(roomName),
purpose: roomPurpose,
}),
);
}
}
// S13 DM half — gated on the row newly created in S8.
if (dmCreated) {
await slackPostMessage(
app.botToken,
dmChannelId,
`Hi <@${operatorUserId}> — I'm ${displayName}, your new agent. This DM is already wired up; just reply here to start.`,
'intro-post',
);
}
return {
slug,
newBotUserId,
operatorUserId,
dmChannelId,
roomChannelId,
...(app.deferredInstall ? { deferredInstall: true } : {}),
};
}
/**
* What the broker generates the avatar from: the template's own description
* when the agent is built from one (its instructions are ignored then), else
* the instructions. The multi-create avatar prefetch keys on this, so both
* sides must call it.
*/
export function avatarDescription(content: Record<string, unknown>): string | undefined {
const text =
typeof content.template === 'string' && content.template
? templateDescription(content.template)
: typeof content.instructions === 'string'
? content.instructions
: undefined;
return text?.slice(0, 300);
}
/** In-host entry — the wrapped create_agent handler's Slack leg (hot-add active). */
export async function runSlackAgentFlow(args: {
content: Record<string, unknown>;
session: Session;
newAgentGroupId: string;
slug: string;
/** Wait budget for a deferred workspace install. Tests shorten it. */
installWait?: { intervalMs?: number; timeoutMs?: number };
}): Promise<OrchestrateSuccess> {
const { content, session, newAgentGroupId, slug } = args;
const displayName =
typeof content.name === 'string' && content.name
? content.name
: ((await getAgentGroup(newAgentGroupId))?.name ?? slug);
const originMg = session.messaging_group_id ? await getMessagingGroup(session.messaging_group_id) : undefined;
return runFlow({
slug,
displayName,
sourceGroupId: session.agent_group_id,
newAgentGroupId,
originInstanceKey: originMg?.instance ?? 'slack',
// messaging_groups store 'slack:<channelId>'; the Web API wants the bare id.
originChannelId: originMg?.platform_id?.replace(/^slack:/, ''),
installWait: args.installWait,
rootDir: process.cwd(),
hotStart: true,
description: avatarDescription(content),
template: typeof content.template === 'string' && content.template ? content.template : undefined,
purpose: typeof content.purpose === 'string' ? content.purpose : undefined,
allowGuests: content.allow_guests === true,
originSession: session,
room: content.room === 'none' ? 'none' : 'own',
});
}
/**
* Out-of-process finish/retry entry (scripts/slack-agent-flow-finish.ts):
* S1–S13 minus the S5 hot-add — a separate process cannot start an adapter
* inside the live host, so the script restarts the service (or says how).
*/
export async function finishSlackAgentFlow(args: {
slug: string;
sourceGroupId: string;
newAgentGroupId: string;
originInstanceKey?: string;
rootDir?: string;
/** Pass true when the original create used allow_guests (plain variant) —
* keeps the finish path's DM wiring congruent with the provisioned app. */
allowGuests?: boolean;
/** Pass 'none' when the original create used room:'none' — keeps the
* finish path from growing a room the caller deliberately skipped. */
room?: 'own' | 'none';
/** Called with the pending-install line when the app is waiting on a
* workspace install approval — the script prints it so a five-minute wait
* does not read as a hang. */
onInstallPending?: (text: string) => void;
}): Promise<OrchestrateSuccess> {
return runFlow({
slug: args.slug,
displayName: (await getAgentGroup(args.newAgentGroupId))?.name ?? args.slug,
sourceGroupId: args.sourceGroupId,
newAgentGroupId: args.newAgentGroupId,
originInstanceKey: args.originInstanceKey ?? 'slack',
rootDir: args.rootDir ?? process.cwd(),
hotStart: false,
allowGuests: args.allowGuests,
room: args.room,
onInstallPending: args.onInstallPending,
});
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |