@alejandroroman/agent-kit 0.1.4 → 0.2.0

package/dist/cli/chat.js

@@ -2,6 +2,7 @@ import { loadConfig } from "../config/index.js";
 import { buildAgentRuntime } from "../bootstrap.js";
 import { ensureOllama } from "./ollama.js";
 import { resolveApiKey } from "./ui.js";
+import { showWhatsNew } from "./whats-new.js";
 import { CONFIG_PATH, DATA_DIR, SKILLS_DIR } from "./paths.js";
 import { startRepl } from "./repl.js";
 export async function chat(agentName) {
@@ -19,6 +20,7 @@ export async function chat(agentName) {
         }
     }
     await resolveApiKey({ save: false });
+    showWhatsNew();
     const config = loadConfig(CONFIG_PATH);
     if (!config.agents[agentName]) {
         const names = Object.keys(config.agents).join(", ");
@@ -31,7 +33,7 @@ export async function chat(agentName) {
             console.log("  (Ollama not running — memory tools unavailable)\n");
         }
     }
-    const runtime = buildAgentRuntime(agentName, config, {
+    const runtime = await buildAgentRuntime(agentName, config, {
         dataDir: DATA_DIR,
         skillsDir: SKILLS_DIR,
     });

package/dist/cli/claude-md-template.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CLAUDE.md template generated by `agent-kit init`.
+ * Gives any Claude Code session full context for working on this project.
+ */
+export declare const CLAUDE_MD_TEMPLATE = "# Agent Kit Project\n\nPersonal AI agent framework \u2014 multi-model agent loop with Slack gateway, cron scheduling, skills, and tool sandboxing.\n\nPowered by [`@alejandroroman/agent-kit`](https://www.npmjs.com/package/@alejandroroman/agent-kit).\n\n## Run Commands\n\n- `pnpm start` \u2014 start all services (cron, Slack, heartbeat, REPL)\n- `pnpm chat` \u2014 lightweight single-agent chat\n- `pnpm create` \u2014 AI-powered agent creation wizard\n\n## Project Layout\n\n```\nagent-kit.json     # Main config \u2014 agents, cron jobs, models, defaults\n.env               # Secrets (API keys, Slack tokens)\ndata/              # Runtime data (per-agent sessions, SOUL.md files, DBs)\n  agents/<name>/\n    SOUL.md        # Agent personality / system prompt\n    sessions/      # JSONL conversation logs\nskills/            # Custom skill definitions\n  <skill-name>/\n    skill.json     # Manifest (name, description, tools list)\n    SKILL.md       # Instructions injected when skill is activated\n    tools/         # Tool implementations (TypeScript)\n```\n\n## Configuration (agent-kit.json)\n\n### Models\n\n```json\n\"models\": [\n  { \"model\": \"anthropic:claude-sonnet-4-6\", \"alias\": \"sonnet\" },\n  { \"model\": \"anthropic:claude-haiku-4-5-20251001\", \"alias\": \"haiku\" }\n]\n```\n\nAgents reference models by alias. The framework handles automatic fallback between models on rate limits/server errors.\n\n### Agent Definition\n\n```json\n\"agents\": {\n  \"my-agent\": {\n    \"displayName\": \"My Agent\",\n    \"emoji\": \"\uD83E\uDD16\",\n    \"model\": \"sonnet\",\n    \"tools\": [\"read_file\", \"write_file\", \"web_search\"],\n    \"skills\": [\"my-skill\"],\n    \"sandbox\": { \"allowedPaths\": [\"data/agents/my-agent/\"] },\n    \"slack\": { \"channelId\": \"C0XXX\", \"channelName\": \"#my-channel\" },\n    \"heartbeat\": { \"enabled\": true, \"intervalMinutes\": 60, \"model\": \"haiku\" },\n    \"can_spawn\": [{ \"agent\": \"helper\", \"tool\": \"delegate\", \"description\": \"...\" }]\n  }\n}\n```\n\n**Key fields:**\n- `tools` \u2014 builtin tools the agent can use (see list below)\n- `skills` \u2014 skill directories to make available via `activate_skill`\n- `sandbox` \u2014 restrict file access (`allowedPaths`) or commands (`allowedCommands`)\n- `slack` \u2014 bind agent to a Slack channel for inbound/outbound messages\n- `heartbeat` \u2014 periodic autonomous check-ins (posts to Slack if something noteworthy)\n- `spawn_only: true` \u2014 agent can only be invoked by other agents, not directly\n\n### Cron Jobs\n\n```json\n\"cron\": [\n  {\n    \"id\": \"daily-task\",\n    \"agent\": \"my-agent\",\n    \"schedule\": \"0 8 * * *\",\n    \"prompt\": \"Activate the my-skill skill. Do the daily task.\",\n    \"enabled\": true\n  }\n]\n```\n\nSchedule uses standard cron syntax. Agents must activate their skill first in the prompt.\n\n### Defaults\n\n```json\n\"defaults\": {\n  \"model\": \"sonnet\",\n  \"maxTokens\": 4096,\n  \"maxIterations\": 20,\n  \"memory\": {\n    \"dbPath\": \"./data/memory.db\",\n    \"ollamaEndpoint\": \"http://localhost:11434\",\n    \"ollamaModel\": \"all-minilm:l6-v2\"\n  }\n}\n```\n\n## Built-in Tools\n\n| Tool | Description |\n|------|-------------|\n| `read_file` | Read a file (respects sandbox allowedPaths) |\n| `write_file` | Write a file (respects sandbox allowedPaths) |\n| `run_command` | Execute a shell command (respects sandbox allowedCommands) |\n| `web_search` | Search the web (Brave or Grok provider) |\n| `store_memory` | Store a memory with content and metadata |\n| `search_memory` | Semantic search across stored memories |\n| `get_memory` | Retrieve a specific memory by ID |\n| `update_memory` | Update an existing memory |\n| `forget_memory` | Delete a memory |\n| `list_memories` | List all memories with optional filtering |\n| `update_agent_config` | Agent updates its own config (allowlisted fields) |\n| `manage_cron` | Agent manages its own cron jobs (CRUD) |\n\nMemory tools require Ollama running with `all-minilm:l6-v2` model.\n\n## Creating Skills\n\nA skill is a directory in `skills/` with:\n\n1. **`skill.json`** \u2014 manifest\n```json\n{\n  \"name\": \"my-skill\",\n  \"description\": \"What this skill does\",\n  \"tools\": [\"my_tool\"],\n  \"prompt\": \"SKILL.md\"\n}\n```\n\n2. **`SKILL.md`** \u2014 instructions injected into agent context when activated\n\n3. **`tools/<name>.ts`** \u2014 tool implementations\n```typescript\nimport type { Tool } from \"@alejandroroman/agent-kit/dist/tools/types.js\";\n\nconst tool: Tool = {\n  name: \"my_tool\",\n  description: \"What this tool does\",\n  parameters: {\n    type: \"object\",\n    properties: {\n      input: { type: \"string\", description: \"The input\" }\n    },\n    required: [\"input\"]\n  },\n  execute: async (args) => {\n    return \"result\";\n  },\n};\n\nexport default tool;\n```\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `ANTHROPIC_API_KEY` | Yes | Anthropic API key for Claude models |\n| `OPENAI_API_KEY` | No | OpenAI API key (for fallback models) |\n| `SLACK_BOT_TOKEN` | No | Slack bot token (xoxb-...) for gateway |\n| `SLACK_APP_TOKEN` | No | Slack app token (xapp-...) for Socket Mode |\n| `BRAVE_SEARCH_API_KEY` | No | Brave Search API key for web_search |\n| `XAI_API_KEY` | No | xAI/Grok API key for web_search |\n\n## Slack Setup\n\n1. Create a Slack app at api.slack.com/apps \u2192 From Manifest (YAML):\n```yaml\ndisplay_information:\n  name: Agent Kit\nsettings:\n  socket_mode_enabled: true\nfeatures:\n  bot_user:\n    display_name: Agent Kit\n    always_online: true\n  event_subscriptions:\n    bot_events:\n      - message.channels\n      - message.groups\noauth_config:\n  scopes:\n    bot:\n      - chat:write\n      - channels:history\n      - channels:read\n      - groups:history\n      - groups:read\n```\n2. Generate an App-Level Token (Settings \u2192 Basic Information) with `connections:write` scope \u2192 `SLACK_APP_TOKEN`\n3. Install to workspace \u2192 copy Bot Token \u2192 `SLACK_BOT_TOKEN`\n4. Create channels, invite the bot (`/invite @Agent Kit`), copy channel IDs\n5. Add `slack` binding to each agent in `agent-kit.json`\n\n## Ollama (for Memory)\n\nMemory tools use Ollama for local embeddings:\n```bash\n# Install: https://ollama.com\nollama pull all-minilm:l6-v2\n# Ollama must be running when agent-kit starts\n```\n\nIf Ollama isn't running, everything else works \u2014 memory tools are just unavailable.\n\n## pnpm v10 Note\n\nIf using pnpm v10+, native dependencies need explicit approval:\n```json\n// In package.json:\n\"pnpm\": { \"onlyBuiltDependencies\": [\"better-sqlite3\"] }\n```\nThen `pnpm install` to rebuild native bindings.\n";

package/dist/cli/claude-md-template.js

@@ -0,0 +1,220 @@
+/**
+ * CLAUDE.md template generated by `agent-kit init`.
+ * Gives any Claude Code session full context for working on this project.
+ */
+export const CLAUDE_MD_TEMPLATE = `# Agent Kit Project
+
+Personal AI agent framework — multi-model agent loop with Slack gateway, cron scheduling, skills, and tool sandboxing.
+
+Powered by [\`@alejandroroman/agent-kit\`](https://www.npmjs.com/package/@alejandroroman/agent-kit).
+
+## Run Commands
+
+- \`pnpm start\` — start all services (cron, Slack, heartbeat, REPL)
+- \`pnpm chat\` — lightweight single-agent chat
+- \`pnpm create\` — AI-powered agent creation wizard
+
+## Project Layout
+
+\`\`\`
+agent-kit.json     # Main config — agents, cron jobs, models, defaults
+.env               # Secrets (API keys, Slack tokens)
+data/              # Runtime data (per-agent sessions, SOUL.md files, DBs)
+  agents/<name>/
+    SOUL.md        # Agent personality / system prompt
+    sessions/      # JSONL conversation logs
+skills/            # Custom skill definitions
+  <skill-name>/
+    skill.json     # Manifest (name, description, tools list)
+    SKILL.md       # Instructions injected when skill is activated
+    tools/         # Tool implementations (TypeScript)
+\`\`\`
+
+## Configuration (agent-kit.json)
+
+### Models
+
+\`\`\`json
+"models": [
+  { "model": "anthropic:claude-sonnet-4-6", "alias": "sonnet" },
+  { "model": "anthropic:claude-haiku-4-5-20251001", "alias": "haiku" }
+]
+\`\`\`
+
+Agents reference models by alias. The framework handles automatic fallback between models on rate limits/server errors.
+
+### Agent Definition
+
+\`\`\`json
+"agents": {
+  "my-agent": {
+    "displayName": "My Agent",
+    "emoji": "🤖",
+    "model": "sonnet",
+    "tools": ["read_file", "write_file", "web_search"],
+    "skills": ["my-skill"],
+    "sandbox": { "allowedPaths": ["data/agents/my-agent/"] },
+    "slack": { "channelId": "C0XXX", "channelName": "#my-channel" },
+    "heartbeat": { "enabled": true, "intervalMinutes": 60, "model": "haiku" },
+    "can_spawn": [{ "agent": "helper", "tool": "delegate", "description": "..." }]
+  }
+}
+\`\`\`
+
+**Key fields:**
+- \`tools\` — builtin tools the agent can use (see list below)
+- \`skills\` — skill directories to make available via \`activate_skill\`
+- \`sandbox\` — restrict file access (\`allowedPaths\`) or commands (\`allowedCommands\`)
+- \`slack\` — bind agent to a Slack channel for inbound/outbound messages
+- \`heartbeat\` — periodic autonomous check-ins (posts to Slack if something noteworthy)
+- \`spawn_only: true\` — agent can only be invoked by other agents, not directly
+
+### Cron Jobs
+
+\`\`\`json
+"cron": [
+  {
+    "id": "daily-task",
+    "agent": "my-agent",
+    "schedule": "0 8 * * *",
+    "prompt": "Activate the my-skill skill. Do the daily task.",
+    "enabled": true
+  }
+]
+\`\`\`
+
+Schedule uses standard cron syntax. Agents must activate their skill first in the prompt.
+
+### Defaults
+
+\`\`\`json
+"defaults": {
+  "model": "sonnet",
+  "maxTokens": 4096,
+  "maxIterations": 20,
+  "memory": {
+    "dbPath": "./data/memory.db",
+    "ollamaEndpoint": "http://localhost:11434",
+    "ollamaModel": "all-minilm:l6-v2"
+  }
+}
+\`\`\`
+
+## Built-in Tools
+
+| Tool | Description |
+|------|-------------|
+| \`read_file\` | Read a file (respects sandbox allowedPaths) |
+| \`write_file\` | Write a file (respects sandbox allowedPaths) |
+| \`run_command\` | Execute a shell command (respects sandbox allowedCommands) |
+| \`web_search\` | Search the web (Brave or Grok provider) |
+| \`store_memory\` | Store a memory with content and metadata |
+| \`search_memory\` | Semantic search across stored memories |
+| \`get_memory\` | Retrieve a specific memory by ID |
+| \`update_memory\` | Update an existing memory |
+| \`forget_memory\` | Delete a memory |
+| \`list_memories\` | List all memories with optional filtering |
+| \`update_agent_config\` | Agent updates its own config (allowlisted fields) |
+| \`manage_cron\` | Agent manages its own cron jobs (CRUD) |
+
+Memory tools require Ollama running with \`all-minilm:l6-v2\` model.
+
+## Creating Skills
+
+A skill is a directory in \`skills/\` with:
+
+1. **\`skill.json\`** — manifest
+\`\`\`json
+{
+  "name": "my-skill",
+  "description": "What this skill does",
+  "tools": ["my_tool"],
+  "prompt": "SKILL.md"
+}
+\`\`\`
+
+2. **\`SKILL.md\`** — instructions injected into agent context when activated
+
+3. **\`tools/<name>.ts\`** — tool implementations
+\`\`\`typescript
+import type { Tool } from "@alejandroroman/agent-kit/dist/tools/types.js";
+
+const tool: Tool = {
+  name: "my_tool",
+  description: "What this tool does",
+  parameters: {
+    type: "object",
+    properties: {
+      input: { type: "string", description: "The input" }
+    },
+    required: ["input"]
+  },
+  execute: async (args) => {
+    return "result";
+  },
+};
+
+export default tool;
+\`\`\`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| \`ANTHROPIC_API_KEY\` | Yes | Anthropic API key for Claude models |
+| \`OPENAI_API_KEY\` | No | OpenAI API key (for fallback models) |
+| \`SLACK_BOT_TOKEN\` | No | Slack bot token (xoxb-...) for gateway |
+| \`SLACK_APP_TOKEN\` | No | Slack app token (xapp-...) for Socket Mode |
+| \`BRAVE_SEARCH_API_KEY\` | No | Brave Search API key for web_search |
+| \`XAI_API_KEY\` | No | xAI/Grok API key for web_search |
+
+## Slack Setup
+
+1. Create a Slack app at api.slack.com/apps → From Manifest (YAML):
+\`\`\`yaml
+display_information:
+  name: Agent Kit
+settings:
+  socket_mode_enabled: true
+features:
+  bot_user:
+    display_name: Agent Kit
+    always_online: true
+  event_subscriptions:
+    bot_events:
+      - message.channels
+      - message.groups
+oauth_config:
+  scopes:
+    bot:
+      - chat:write
+      - channels:history
+      - channels:read
+      - groups:history
+      - groups:read
+\`\`\`
+2. Generate an App-Level Token (Settings → Basic Information) with \`connections:write\` scope → \`SLACK_APP_TOKEN\`
+3. Install to workspace → copy Bot Token → \`SLACK_BOT_TOKEN\`
+4. Create channels, invite the bot (\`/invite @Agent Kit\`), copy channel IDs
+5. Add \`slack\` binding to each agent in \`agent-kit.json\`
+
+## Ollama (for Memory)
+
+Memory tools use Ollama for local embeddings:
+\`\`\`bash
+# Install: https://ollama.com
+ollama pull all-minilm:l6-v2
+# Ollama must be running when agent-kit starts
+\`\`\`
+
+If Ollama isn't running, everything else works — memory tools are just unavailable.
+
+## pnpm v10 Note
+
+If using pnpm v10+, native dependencies need explicit approval:
+\`\`\`json
+// In package.json:
+"pnpm": { "onlyBuiltDependencies": ["better-sqlite3"] }
+\`\`\`
+Then \`pnpm install\` to rebuild native bindings.
+`;

package/dist/cli/config-writer.js

@@ -103,6 +103,9 @@ export function scaffoldProjectPackageJson(projectDir, projectName) {
         dependencies: {
             "@alejandroroman/agent-kit": "^0.1.0",
         },
+        pnpm: {
+            onlyBuiltDependencies: ["better-sqlite3"],
+        },
     };
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
     // Create .gitignore if missing

package/dist/cli/env.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parse a .env file into a key-value map.
+ * Strips quotes, ignores comments and blank lines.
+ */
+export declare function loadEnvFile(envPath: string): Record<string, string>;
+/**
+ * Upsert a key in a .env file. Replaces if exists, appends if not.
+ * Values are always quoted to prevent shell issues.
+ */
+export declare function upsertEnvKey(envPath: string, key: string, value: string): void;
+/**
+ * Load specific keys from .env into process.env (if not already set).
+ */
+export declare function loadEnvIntoProcess(envPath: string, keys: string[]): void;

package/dist/cli/env.js

@@ -0,0 +1,68 @@
+import * as fs from "fs";
+/**
+ * Parse a .env file into a key-value map.
+ * Strips quotes, ignores comments and blank lines.
+ */
+export function loadEnvFile(envPath) {
+    if (!fs.existsSync(envPath))
+        return {};
+    const result = {};
+    const content = fs.readFileSync(envPath, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Upsert a key in a .env file. Replaces if exists, appends if not.
+ * Values are always quoted to prevent shell issues.
+ */
+export function upsertEnvKey(envPath, key, value) {
+    const quotedLine = `${key}="${value}"`;
+    if (!fs.existsSync(envPath)) {
+        fs.writeFileSync(envPath, quotedLine + "\n", { mode: 0o600 });
+        return;
+    }
+    const content = fs.readFileSync(envPath, "utf-8");
+    const lines = content.split("\n");
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^${escaped}\\s*=`);
+    let replaced = false;
+    const updated = lines.map((line) => {
+        if (pattern.test(line.trim())) {
+            replaced = true;
+            return quotedLine;
+        }
+        return line;
+    });
+    if (!replaced) {
+        const needsNewline = content.length > 0 && !content.endsWith("\n");
+        fs.writeFileSync(envPath, content + (needsNewline ? "\n" : "") + quotedLine + "\n", { mode: 0o600 });
+    }
+    else {
+        fs.writeFileSync(envPath, updated.join("\n"), { mode: 0o600 });
+    }
+}
+/**
+ * Load specific keys from .env into process.env (if not already set).
+ */
+export function loadEnvIntoProcess(envPath, keys) {
+    const env = loadEnvFile(envPath);
+    for (const key of keys) {
+        if (!process.env[key] && env[key]) {
+            process.env[key] = env[key];
+        }
+    }
+}

package/dist/cli/init.js

@@ -5,7 +5,10 @@ import { banner, isCancel, done, resolveApiKey } from "./ui.js";
 import { checkOllama } from "./ollama.js";
 import { createFreshConfig, scaffoldProjectPackageJson } from "./config-writer.js";
 import { runSetupAgent } from "./setup-agent/index.js";
+import { setupSlack } from "./slack-setup.js";
 import { CONFIG_PATH, DATA_DIR, SKILLS_DIR } from "./paths.js";
+import { CLAUDE_MD_TEMPLATE } from "./claude-md-template.js";
+import * as path from "path";
 function detectPackageManager() {
     try {
         execSync("pnpm --version", { stdio: "ignore" });
@@ -40,6 +43,11 @@ export async function init() {
         createFreshConfig({ configPath: CONFIG_PATH });
         fs.mkdirSync(DATA_DIR, { recursive: true });
         fs.mkdirSync(SKILLS_DIR, { recursive: true });
+        // Generate CLAUDE.md for Claude Code context
+        const claudeMdPath = path.join(process.cwd(), "CLAUDE.md");
+        if (!fs.existsSync(claudeMdPath)) {
+            fs.writeFileSync(claudeMdPath, CLAUDE_MD_TEMPLATE);
+        }
     }
     catch (err) {
         s.stop(`Failed to create project: ${err instanceof Error ? err.message : err}`);
@@ -79,4 +87,6 @@ export async function init() {
     });
     console.log();
     done(summary);
+    // Offer Slack setup after agent creation
+    await setupSlack({ configPath: CONFIG_PATH, fromInit: true });
 }

package/dist/cli/slack-setup.d.ts

@@ -0,0 +1,6 @@
+interface SetupSlackOpts {
+    configPath: string;
+    fromInit?: boolean;
+}
+export declare function setupSlack(opts: SetupSlackOpts): Promise<void>;
+export {};

package/dist/cli/slack-setup.js

@@ -0,0 +1,234 @@
+import * as path from "path";
+import { execFileSync } from "child_process";
+import * as p from "@clack/prompts";
+import { isCancel } from "./ui.js";
+import { upsertEnvKey, loadEnvFile } from "./env.js";
+import { readRawConfig, writeConfig } from "./config-writer.js";
+import { loadConfig } from "../config/index.js";
+const SLACK_MANIFEST = `display_information:
+  name: Agent Kit
+settings:
+  socket_mode_enabled: true
+features:
+  bot_user:
+    display_name: Agent Kit
+    always_online: true
+  event_subscriptions:
+    bot_events:
+      - message.channels
+      - message.groups
+oauth_config:
+  scopes:
+    bot:
+      - chat:write
+      - channels:history
+      - channels:read
+      - groups:history
+      - groups:read`;
+function openBrowser(url) {
+    try {
+        const cmd = process.platform === "darwin" ? "open"
+            : process.platform === "win32" ? "start"
+                : "xdg-open";
+        execFileSync(cmd, [url], { stdio: "ignore" });
+    }
+    catch {
+        p.log.warn(`Could not open browser. Visit: ${url}`);
+    }
+}
+export async function setupSlack(opts) {
+    const envPath = path.join(process.cwd(), ".env");
+    // 1. Opt-in (only during init)
+    if (opts.fromInit) {
+        const wantSlack = await p.confirm({
+            message: "Would you like to connect Slack?",
+        });
+        if (isCancel(wantSlack) || !wantSlack)
+            return;
+    }
+    // Check for existing tokens
+    const existingEnv = loadEnvFile(envPath);
+    const hasAppToken = !!existingEnv.SLACK_APP_TOKEN;
+    const hasBotToken = !!existingEnv.SLACK_BOT_TOKEN;
+    let skipTokens = false;
+    if (hasAppToken && hasBotToken) {
+        const keep = await p.confirm({
+            message: "Slack tokens already exist in .env. Keep them?",
+        });
+        if (isCancel(keep))
+            return;
+        if (keep) {
+            skipTokens = true;
+            process.env.SLACK_APP_TOKEN ??= existingEnv.SLACK_APP_TOKEN;
+            process.env.SLACK_BOT_TOKEN ??= existingEnv.SLACK_BOT_TOKEN;
+            p.log.info("Using existing tokens from .env");
+        }
+    }
+    // 2. Instructions — Create App
+    if (!skipTokens) {
+        p.log.step("Step 1: Create Slack App");
+        console.log();
+        console.log("  Go to api.slack.com/apps → Create New App → From a manifest");
+        console.log();
+        const openPage = await p.confirm({
+            message: "Open api.slack.com in your browser?",
+        });
+        if (!isCancel(openPage) && openPage) {
+            openBrowser("https://api.slack.com/apps");
+        }
+        console.log();
+        console.log("  Select your workspace, then paste this manifest:");
+        console.log();
+        for (const line of SLACK_MANIFEST.split("\n")) {
+            console.log(`    ${line}`);
+        }
+        console.log();
+        console.log("  Click Create.");
+        console.log();
+        // 3. Instructions — App Token
+        p.log.step("Step 2: Generate App-Level Token");
+        console.log();
+        console.log("  Settings → Basic Information → App-Level Tokens");
+        console.log("  Click 'Generate Token and Scopes'");
+        console.log("  Name: socket-mode  |  Scope: connections:write");
+        console.log("  Copy the xapp-... token");
+        console.log();
+        // 4. Collect App Token
+        const appToken = await p.password({
+            message: "Paste App Token (xapp-...):",
+            validate: (val) => {
+                if (!val?.trim())
+                    return "App token is required";
+                if (!val.startsWith("xapp-"))
+                    return "Token should start with xapp-";
+            },
+        });
+        if (isCancel(appToken))
+            return;
+        upsertEnvKey(envPath, "SLACK_APP_TOKEN", appToken.trim());
+        process.env.SLACK_APP_TOKEN = appToken.trim();
+        p.log.success("App token saved to .env");
+        // 5. Instructions — Bot Token
+        p.log.step("Step 3: Install to Workspace");
+        console.log();
+        console.log("  Settings → Install App → Install to Workspace");
+        console.log("  Authorize, then copy the Bot User OAuth Token (xoxb-...)");
+        console.log();
+        // 6. Collect Bot Token
+        const botToken = await p.password({
+            message: "Paste Bot Token (xoxb-...):",
+            validate: (val) => {
+                if (!val?.trim())
+                    return "Bot token is required";
+                if (!val.startsWith("xoxb-"))
+                    return "Token should start with xoxb-";
+            },
+        });
+        if (isCancel(botToken))
+            return;
+        upsertEnvKey(envPath, "SLACK_BOT_TOKEN", botToken.trim());
+        process.env.SLACK_BOT_TOKEN = botToken.trim();
+        p.log.success("Bot token saved to .env");
+    } // end if (!skipTokens)
+    // 7. Channel Binding
+    let config;
+    try {
+        config = loadConfig(opts.configPath);
+    }
+    catch (err) {
+        p.log.error(`Could not load config: ${err instanceof Error ? err.message : err}`);
+        p.log.info("Slack tokens were saved to .env. Run `agent-kit slack-setup` again after fixing your config.");
+        return;
+    }
+    const agentNames = Object.keys(config.agents);
+    if (agentNames.length === 0) {
+        p.log.info("No agents configured yet. Run `agent-kit create` first, then `agent-kit slack-setup` to bind channels.");
+    }
+    else {
+        p.log.step("Step 4: Connect agents to Slack channels");
+        console.log();
+        console.log("  Create channels in Slack, then invite the bot: /invite @Agent Kit");
+        console.log("  Get channel IDs: right-click channel → View channel details → copy ID (starts with C)");
+        console.log();
+        const raw = readRawConfig(opts.configPath);
+        if (!raw) {
+            p.log.error("Could not read agent-kit.json");
+            return;
+        }
+        const agents = raw.agents;
+        if (!agents) {
+            p.log.error("No agents section in config");
+            return;
+        }
+        const usedChannels = new Map(); // channelId → agentName
+        // Collect already-bound channels
+        for (const [name, def] of Object.entries(agents)) {
+            const slack = def.slack;
+            if (slack?.channelId) {
+                usedChannels.set(slack.channelId, name);
+            }
+        }
+        for (const name of agentNames) {
+            const agentDef = config.agents[name];
+            const emoji = agentDef.emoji ?? " ";
+            const display = agentDef.displayName ?? name;
+            // Skip if already bound
+            if (agentDef.slack) {
+                p.log.info(`${emoji}  ${display} — already bound to ${agentDef.slack.channelName}`);
+                continue;
+            }
+            const bind = await p.confirm({
+                message: `Connect ${emoji}  ${display} to a Slack channel?`,
+            });
+            if (isCancel(bind))
+                return;
+            if (!bind)
+                continue;
+            const channelId = await p.text({
+                message: "Channel ID (e.g. C0123456789):",
+                validate: (val) => {
+                    if (!val?.trim())
+                        return "Channel ID is required";
+                    if (!/^[CG][A-Z0-9]{8,}$/.test(val.trim())) {
+                        return "Channel ID should start with C or G followed by uppercase letters/numbers";
+                    }
+                    const existing = usedChannels.get(val.trim());
+                    if (existing) {
+                        return `Channel already bound to agent "${existing}"`;
+                    }
+                },
+            });
+            if (isCancel(channelId))
+                return;
+            const channelName = await p.text({
+                message: "Channel name (e.g. #finances):",
+                validate: (val) => {
+                    if (!val?.trim())
+                        return "Channel name is required";
+                },
+            });
+            if (isCancel(channelName))
+                return;
+            const id = channelId.trim();
+            const cName = channelName.trim();
+            // Update raw config
+            agents[name] = {
+                ...agents[name],
+                slack: { channelId: id, channelName: cName },
+            };
+            usedChannels.set(id, name);
+            p.log.success(`${emoji}  ${display} → ${cName}`);
+        }
+        try {
+            writeConfig(opts.configPath, raw);
+        }
+        catch (err) {
+            p.log.error(`Could not save config: ${err instanceof Error ? err.message : err}`);
+            p.log.info("Slack tokens were saved, but channel bindings were not persisted.");
+            return;
+        }
+    }
+    // 8. Done
+    console.log();
+    p.log.success("Slack configured! Start with `pnpm start` to connect.");
+}