Skip to content

nanocoai/nanoclaw / .claude/skills/slack-agent-flow

slack-agent-flow

Flagged

Let 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/index.ts

View on GitHub
/**
 * slack-agent-flow module — guarded re-registration of `create_agent`.
 *
 * Re-registers the delivery action with the SAME guard pieces as upstream
 * (agents.create decision, validateCreateAgent precheck) and a handler that
 * first runs the upstream `createAgent()` (with its premature success notify
 * suppressed on the Slack path — see slackAwareCreateAgent), then — only when
 * the request originated from a Slack session — provisions a dedicated Slack
 * bot for the new group (orchestrate.ts). The barrel imports this module AFTER
 * agent-to-agent's registration, so this entry wins; the expected boot log is
 * `Delivery action handler overwritten`. Approved replays re-enter this
 * wrapper automatically — reenterGuardedDeliveryAction resolves the entry at
 * call time, so no approval-handler re-registration is needed.
 *
 * Also registers the agent-facing room actions: `create_room` (one
 * MPIM with N bots + the operator over ensureAgentRoom) and `add_to_room`
 * (superset re-open — MPIM fork), each guard-wrapped with the same
 * cli_scope trust split as create_agent (./guard.ts, ./room-actions.ts).
 *
 * The handler never touches inbound DBs (guarded handlers replay without
 * one); all requester notifications go through the approvals module's
 * notifyAgent. Token values never appear in notify texts or logs.
 */
import { quoteForCard } from '../../card-text.js';
import { SlackApiError } from '../../channels/slack-lib.js';
import { reenterGuardedDeliveryAction, registerDeliveryAction, registerDeliveryBatchPreview } from '../../delivery.js';
import { getAgentGroup } from '../../db/agent-groups.js';
import { getMessagingGroup } from '../../db/messaging-groups.js';
import { log } from '../../log.js';
import type { Session } from '../../types.js';
import { getDestinationByName, normalizeName } from '../agent-to-agent/db/agent-destinations.js';
import {
  createAgent,
  createAgentHoldPayload,
  requestCreateAgentHold,
  templateApprovalNote,
  validateCreateAgent,
} from '../agent-to-agent/create-agent.js';
import { agentsCreate } from '../agent-to-agent/guard.js';
import { notifyAgent, registerApprovalHandler, requestApproval } from '../approvals/index.js';
import { roomsAddAgent, roomsCreate } from './guard.js';
import { avatarDescription, dedupeSlug, deriveInstanceSlug, runSlackAgentFlow } from './orchestrate.js';
import {
  handleAddToRoom,
  handleCreateRoom,
  requestAddToRoomHold,
  requestCreateRoomHold,
  validateAddToRoom,
  validateCreateRoom,
} from './room-actions.js';
import { pendingInstall, prefetchAvatar, resolveProvisioningCredential } from './provision.js';
import { SlackFlowError } from './types.js';

/** The Slack gate: the request came in through a Slack-channel session. */
async function isSlackOriginSession(session: Session): Promise<boolean> {
  if (!session.messaging_group_id) return false;
  return (await getMessagingGroup(session.messaging_group_id))?.channel_type === 'slack';
}

// Avatar prefetch for multi-agent creates ("build me a team"): the batch
// preview sees every create_agent row in the session's outbound batch before
// they are processed sequentially, and starts all their avatar generations in
// parallel — each is an independent async Lambda on the broker, so N waits
// collapse to ~one (~23s). Gated on ≥2 creates: a single create starts its
// flow immediately anyway, and skipping the single case means a guard-HELD
// lone request never generates an avatar it might not get approval for.
// The (displayName, description) derivation MUST mirror runSlackAgentFlow /
// orchestrate exactly (avatarDescription) — a mismatch is harmless (fresh
// request) but wastes the prefetch.
registerDeliveryBatchPreview(async (batch, session) => {
  if (!(await isSlackOriginSession(session))) return;
  const creates = batch
    .filter((m) => m.kind === 'system')
    .map((m) => {
      try {
        return JSON.parse(m.content) as Record<string, unknown>;
      } catch {
        return null;
      }
    })
    .filter(
      (c): c is Record<string, unknown> =>
        c !== null && c.action === 'create_agent' && typeof c.name === 'string' && c.name !== '',
    );
  if (creates.length < 2) return;
  const credential = resolveProvisioningCredential(process.cwd());
  if (credential?.mode !== 'broker') return;
  for (const c of creates) {
    prefetchAvatar(credential.baseUrl, credential.installToken, c.name as string, avatarDescription(c));
  }
  log.info('Avatar prefetch started for multi-create batch', { count: creates.length });
});

function successText(
  name: string,
  roomChannelId: string | undefined,
  deferredInstall = false,
  template?: string,
): string {
  // The user already knows they were waiting on their workspace — name what
  // unblocked it so the relay reads as an ending, not a fresh announcement.
  const installed = deferredInstall ? ' The workspace approved the install, which is what the wait was for.' : '';
  const agent = template ? `Agent "${name}" (built from the template "${template}")` : `Agent "${name}"`;
  // room:'none': no shared room was opened — the multi-create
  // pattern finishes with one create_room naming every agent.
  if (roomChannelId === undefined) {
    return (
      `${agent} is live on Slack with its own bot and a DM with the operator. No shared room was ` +
      `opened (room:'none') — when the set is complete, open ONE room for all of them with create_room. ` +
      `It came online just now; if it doesn't respond within a minute, an operator can run: bash setup/lib/restart.sh` +
      installed
    );
  }
  return (
    `${agent} is live on Slack with its own bot. I opened a DM between it and the operator, ` +
    `and a shared room (${roomChannelId}) where you, I, and it can talk — @-mention it there to engage it. ` +
    `It came online just now; if it doesn't respond within a minute, an operator can run: bash setup/lib/restart.sh` +
    installed
  );
}

function failureText(
  name: string,
  localName: string,
  step: string,
  message: string,
  newAgentGroupId: string,
  slug: string,
  sourceGroupId: string,
  roomNone: boolean,
): string {
  // room:'none' must survive into the printed finish command too — omitting
  // it would make the retry grow a room the multi-create pattern skipped.
  return (
    `Agent "${name}" was created and is reachable via send_message({ to: "${localName}", ... }), ` +
    `but its Slack setup failed at step '${step}': ${message}. An operator can finish it with: ` +
    `pnpm exec tsx scripts/slack-agent-flow-finish.ts --group ${newAgentGroupId} --name ${slug} ` +
    `--source-group ${sourceGroupId}${roomNone ? ' --room none' : ''} [--origin-instance <key>] [--restart]`
  );
}

/** Run the Slack leg for an already-created agent group and report the outcome. */
async function runSlackLeg(
  content: Record<string, unknown>,
  session: Session,
  args: {
    name: string;
    localName: string;
    newAgentGroupId: string;
    slug: string;
  },
): Promise<void> {
  const { name, localName, newAgentGroupId, slug } = args;
  try {
    const r = await runSlackAgentFlow({ content, session, newAgentGroupId, slug });
    const template = typeof content.template === 'string' && content.template ? content.template : undefined;
    await notifyAgent(session, successText(name, r.roomChannelId, r.deferredInstall, template));
  } catch (err) {
    // SlackApiError carries the flow step id its call site passed to the
    // shared Slack lib — surface it like a typed flow step.
    const step = err instanceof SlackFlowError || err instanceof SlackApiError ? err.step : 'unknown';
    const message = err instanceof Error ? err.message : String(err);
    await notifyAgent(
      session,
      failureText(
        name,
        localName,
        step,
        message,
        newAgentGroupId,
        slug,
        session.agent_group_id,
        content.room === 'none',
      ),
    );
    log.error('slack-agent-flow failed', { step });
  }
}

async function slackAwareCreateAgent(content: Record<string, unknown>, session: Session): Promise<void> {
  const name = typeof content.name === 'string' ? content.name : '';
  const localName = normalizeName(name);
  const before = await getDestinationByName(session.agent_group_id, localName);
  const slackOrigin = await isSlackOriginSession(session);

  // Resume, not collide: the agent group exists and its Slack app exists, but
  // the workspace never approved the install, so the flow parked. Asking for
  // the same agent again is how a user says "finish that" — take them back to
  // waiting on the app they already have rather than reporting a name clash
  // (upstream's answer) or provisioning a second one.
  if (slackOrigin && before?.target_type === 'agent' && name) {
    const slug = await dedupeSlug(deriveInstanceSlug(name), before.target_id);
    if (pendingInstall(process.cwd(), slug)) {
      await runSlackLeg(content, session, { name, localName, newAgentGroupId: before.target_id, slug });
      return;
    }
  }

  // Upstream behavior byte-for-byte on non-Slack sessions. On the Slack path
  // the upstream "created — you can now message it" success notify is
  // suppressed: it fires BEFORE Slack provisioning, so relaying it would
  // report "done" ~a minute early — this wrapper's successText/failureText
  // is the only completion signal. Upstream error notifies (collision,
  // invalid folder) still fire either way.
  await createAgent(content, session, slackOrigin ? { suppressCreatedNotify: true } : undefined);

  const after = await getDestinationByName(session.agent_group_id, localName);
  // Creation bailed or collided — upstream already answered the requester.
  if (!after || after.target_type !== 'agent' || before) return;
  // Non-Slack sessions (and task/a2a sessions with no messaging group) behave exactly as upstream.
  if (!slackOrigin) return;

  await runSlackLeg(content, session, {
    name,
    localName,
    newAgentGroupId: after.target_id,
    slug: await dedupeSlug(deriveInstanceSlug(name), after.target_id),
  });
}

/**
 * Slack-aware hold: upstream's payload (createAgentHoldPayload, which carries
 * the template) plus the Slack fields, so the approved replay re-enters this
 * wrapper unchanged; the card also tells the admin a Slack bot comes with it.
 */
async function requestSlackCreateAgentHold(content: Record<string, unknown>, session: Session): Promise<void> {
  if (!(await isSlackOriginSession(session))) {
    await requestCreateAgentHold(content, session);
    return;
  }
  const name = typeof content.name === 'string' ? content.name : '';
  const sourceGroup = await getAgentGroup(session.agent_group_id);
  if (!sourceGroup) return;

  await requestApproval({
    session,
    agentName: sourceGroup.name,
    action: 'create_agent',
    // allow_guests must survive the hold: the approved replay re-enters the
    // wrapper with this payload, and dropping it would silently upgrade a
    // guest-accessible request to the agent-view variant.
    payload: {
      ...createAgentHoldPayload(content),
      ...(typeof content.purpose === 'string' ? { purpose: content.purpose } : {}),
      ...(content.allow_guests === true ? { allow_guests: true } : {}),
      // room:'none' must survive the hold too — dropping it would grow a
      // room the multi-create pattern deliberately skipped.
      ...(content.room === 'none' ? { room: 'none' } : {}),
    },
    title: `Create agent: ${quoteForCard(name)}`,
    question:
      `Agent ${quoteForCard(sourceGroup.name)} wants to create a new sub-agent ${quoteForCard(name)} AND provision a dedicated ` +
      `Slack bot for it (new Slack app, DM with you, and a shared three-way room).${templateApprovalNote(content)} Approve?`,
  });
}

registerDeliveryAction('create_agent', slackAwareCreateAgent, {
  guardAction: agentsCreate,
  precheck: validateCreateAgent,
  requestHold: requestSlackCreateAgentHold,
  onDeny: (_content, session, reason) => notifyAgent(session, `create_agent denied: ${reason}`),
});

// Agent-facing room actions — guard-wrapped like create_agent:
// global-scope groups act directly, everything else holds for the admin
// chain, and the approval continuation re-enters the same wrapped entry with
// the approval row as its grant.
registerDeliveryAction('create_room', handleCreateRoom, {
  guardAction: roomsCreate,
  precheck: validateCreateRoom,
  requestHold: requestCreateRoomHold,
  onDeny: (_content, session, reason) => notifyAgent(session, `create_room denied: ${reason}`),
});
registerApprovalHandler('create_room', reenterGuardedDeliveryAction('create_room'));

registerDeliveryAction('add_to_room', handleAddToRoom, {
  guardAction: roomsAddAgent,
  precheck: validateAddToRoom,
  requestHold: requestAddToRoomHold,
  onDeny: (_content, session, reason) => notifyAgent(session, `add_to_room denied: ${reason}`),
});
registerApprovalHandler('add_to_room', reenterGuardedDeliveryAction('add_to_room'));
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall