@cursor/july 0.1.52 → 0.1.53

package/AGENTS.md

@@ -203,6 +203,7 @@ distinct bot handle:
 agent-serve slack setup
 agent-serve slack create --dir ./my-agent --channel-posts
 # envPrefix from the directory name (MY_AGENT_SLACK_*)
+# Manual path: agent-serve slack init --manual --dir ./my-agent
 agent-serve slack doctor --prefix MY_AGENT
 agent-serve dev ./my-agent
 ```

package/README.md

@@ -952,14 +952,16 @@ agent-to-agent only (no Slack channel).
 
 For Socket Mode apps (channel watch / approvals), run
 `agent-serve slack create`. It opens the dashboard wizard, creates and
-installs the app, and writes the token pair to `.env.local`. Do not paste
-a manifest at api.slack.com.
+installs the app, and writes the token pair to `.env.local`. To own the
+Slack app yourself, run `agent-serve slack init --manual` and paste the
+manifests at api.slack.com.
 
 CLI (`agent-serve slack …`; guided setup in `skills/setup-slack/SKILL.md`):
 
 ```bash
 agent-serve slack create --dir ./my-agent           # dashboard wizard (dev app)
 agent-serve slack create --dir ./my-agent --prod    # prod app
+agent-serve slack init --manual --dir ./my-agent    # manifests for api.slack.com
 agent-serve slack setup
 agent-serve slack doctor --prefix MY_AGENT
 ```

package/dist/bin/agent-serve.js

@@ -496,6 +496,7 @@ function main(argv) {
                 "slack-team": { type: "string" },
                 icon: { type: "string" },
                 force: { type: "boolean", default: false },
+                manual: { type: "boolean", default: false },
                 repo: { type: "string", multiple: true },
                 org: { type: "string" },
                 "cursor-events": { type: "boolean", default: false },
@@ -555,6 +556,7 @@ function main(argv) {
                     apiKey: values["api-key"],
                     icon: values.icon,
                     force: values.force,
+                    manual: values.manual,
                     iconSource: positionals[0] === "icon" ? positionals[1] : undefined,
                 });
             }

package/dist/channels/slack/init.d.ts

@@ -1,20 +1,27 @@
 /**
  * Scaffold a Slack channel into an agent-serve project.
+ *
+ * `initSlackChannel` is the create-safe writer: `agent/channels/slack.ts`
+ * only. DIY manifests for paste at api.slack.com live in
+ * {@link initSlackManual} so `slack create` cannot reach them.
  */
 export interface InitSlackOptions {
     dir: string;
     /** Display name for the Slack app. Defaults to directory basename. */
     name?: string;
-    description?: string;
     /**
      * Env prefix for tokens (`MY_AGENT` → `MY_AGENT_SLACK_BOT_TOKEN`). Defaults to
      * the directory basename so multi-agent serve can mount several Slack bots.
      * Pass `""` to use the shared `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` globals.
      */
     envPrefix?: string;
+}
+export interface InitSlackManualOptions extends InitSlackOptions {
+    description?: string;
     /**
-     * Subscribe the generated app to `message.channels` + `message.groups`
-     * for the opt-in channel watch (`engagement.channelPosts`).
+     * Subscribe the generated manifests to `message.channels` +
+     * `message.groups` for the opt-in channel watch
+     * (`engagement.channelPosts` on `slackChannel`).
      */
     channelPosts?: boolean;
 }
@@ -27,5 +34,11 @@ export interface InitSlackResult {
         app: string;
     };
 }
+/** Create-safe: write `agent/channels/slack.ts` only. */
 export declare function initSlackChannel(options: InitSlackOptions): Promise<InitSlackResult>;
+/**
+ * `slack init --manual`: channel file plus DIY manifests
+ * (`managedByCursor: false`), env.example, and setup-status.json.
+ */
+export declare function initSlackManual(options: InitSlackManualOptions): Promise<InitSlackResult>;
 //# sourceMappingURL=init.d.ts.map

package/dist/channels/slack/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAuC1B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/init.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAoED,yDAAyD;AACzD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAgD1B"}

package/dist/channels/slack/init.js

@@ -1,5 +1,9 @@
 /**
  * Scaffold a Slack channel into an agent-serve project.
+ *
+ * `initSlackChannel` is the create-safe writer: `agent/channels/slack.ts`
+ * only. DIY manifests for paste at api.slack.com live in
+ * {@link initSlackManual} so `slack create` cannot reach them.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -14,28 +18,46 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { PACKAGE_NAME } from "../../internal/distribution.js";
 import { envPrefixFromName, slackEnvKeys } from "./credentials.js";
-export function initSlackChannel(options) {
+import { buildSlackManifestPair, slackManifestFileEntries, } from "./manifest.js";
+import { initialSlackSetupStatus } from "./setup.js";
+function resolveSlackInitTarget(options) {
+    var _a, _b;
+    const rootDir = resolve(options.dir);
+    const envPrefix = options.envPrefix === ""
+        ? undefined
+        : ((_a = options.envPrefix) !== null && _a !== void 0 ? _a : envPrefixFromName(basename(rootDir)));
+    return {
+        rootDir,
+        name: (_b = options.name) !== null && _b !== void 0 ? _b : basename(rootDir),
+        envPrefix,
+        envKeys: slackEnvKeys(envPrefix),
+    };
+}
+function writeExclusive(rootDir, rel, contents) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a;
-        const rootDir = resolve(options.dir);
-        const envPrefix = options.envPrefix === ""
-            ? undefined
-            : ((_a = options.envPrefix) !== null && _a !== void 0 ? _a : envPrefixFromName(basename(rootDir)));
-        const envKeys = slackEnvKeys(envPrefix);
-        const written = [];
-        const abs = join(rootDir, "agent/channels/slack.ts");
+        const abs = join(rootDir, rel);
         yield mkdir(join(abs, ".."), { recursive: true });
-        const envPrefixLine = envPrefix === undefined
-            ? ""
-            : `  envPrefix: ${JSON.stringify(envPrefix)},\n`;
-        yield writeFile(abs, `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";
+        yield writeFile(abs, contents, { flag: "wx" });
+    });
+}
+function slackChannelSource(target, kind) {
+    const envPrefixLine = target.envPrefix === undefined
+        ? ""
+        : `  envPrefix: ${JSON.stringify(target.envPrefix)},\n`;
+    const tokenLines = kind === "manual"
+        ? ` * Tokens: ${target.envKeys.bot} + ${target.envKeys.app}\n * (see .agent-serve/slack/env.example).`
+        : ` * Tokens: ${target.envKeys.bot} + ${target.envKeys.app}`;
+    const setupLine = kind === "manual"
+        ? " * Full setup: agent-serve slack setup"
+        : " * Full setup: agent-serve slack create --dir .";
+    return `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";
 
 /**
  * Slack channel (Socket Mode).
  *
- * Tokens: ${envKeys.bot} + ${envKeys.app}
+${tokenLines}
  *
- * Full setup: agent-serve slack create --dir .
+${setupLine}
  */
 export default slackChannel({
 ${envPrefixLine}  // Streaming and thinking steps default to true.
@@ -44,8 +66,60 @@ ${envPrefixLine}  // Streaming and thinking steps default to true.
     { title: "Status", message: "What are you working on?" },
   ],
 });
-`, { flag: "wx" });
-        written.push("agent/channels/slack.ts");
-        return { rootDir, files: written, envPrefix, envKeys };
+`;
+}
+/** Create-safe: write `agent/channels/slack.ts` only. */
+export function initSlackChannel(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const target = resolveSlackInitTarget(options);
+        yield writeExclusive(target.rootDir, "agent/channels/slack.ts", slackChannelSource(target, "create"));
+        return {
+            rootDir: target.rootDir,
+            files: ["agent/channels/slack.ts"],
+            envPrefix: target.envPrefix,
+            envKeys: target.envKeys,
+        };
+    });
+}
+/**
+ * `slack init --manual`: channel file plus DIY manifests
+ * (`managedByCursor: false`), env.example, and setup-status.json.
+ */
+export function initSlackManual(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const target = resolveSlackInitTarget(options);
+        const files = [];
+        const write = (rel, contents) => __awaiter(this, void 0, void 0, function* () {
+            yield writeExclusive(target.rootDir, rel, contents);
+            files.push(rel);
+        });
+        yield write("agent/channels/slack.ts", slackChannelSource(target, "manual"));
+        const pair = buildSlackManifestPair({
+            name: target.name,
+            managedByCursor: false,
+            description: options.description,
+            channelPosts: options.channelPosts,
+        });
+        for (const file of slackManifestFileEntries(pair)) {
+            yield write(`.agent-serve/slack/${file.name}`, file.contents);
+        }
+        yield write(".agent-serve/slack/env.example", `# Copy to .env.local (or export in your shell). Use the *dev* Slack app
+# for local development; use the Prod app tokens in deployment secrets.
+#
+# Multi-agent serve needs a distinct Slack app (and token pair) per agent.
+
+${target.envKeys.bot}=xoxb-...
+${target.envKeys.app}=xapp-...
+`);
+        yield write(".agent-serve/slack/setup-status.json", `${JSON.stringify(initialSlackSetupStatus({
+            envPrefix: target.envPrefix,
+            envKeys: target.envKeys,
+        }), null, 2)}\n`);
+        return {
+            rootDir: target.rootDir,
+            files,
+            envPrefix: target.envPrefix,
+            envKeys: target.envKeys,
+        };
     });
 }

package/dist/channels/slack/manifest.d.ts

@@ -67,4 +67,12 @@ export declare function buildSlackManifestPair(options: Omit<SlackManifestOption
     dev: SlackAppManifest;
     prod: SlackAppManifest;
 };
+/** Relative names under `.agent-serve/slack/`. */
+export declare function slackManifestFileEntries(pair: {
+    dev: SlackAppManifest;
+    prod: SlackAppManifest;
+}, env?: "dev" | "prod" | "both"): ReadonlyArray<{
+    name: "manifest.dev.json" | "manifest.prod.json";
+    contents: string;
+}>;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/channels/slack/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,iDACE,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE;QACR,QAAQ,EAAE;YACR,YAAY,EAAE,MAAM,CAAC;YACrB,aAAa,EAAE,OAAO,CAAC;SACxB,CAAC;QACF,cAAc,CAAC,EAAE;YACf,qBAAqB,EAAE,MAAM,CAAC;YAC9B,iBAAiB,EAAE,KAAK,CAAC;gBAAE,KAAK,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SAC9D,CAAC;QACF,QAAQ,CAAC,EAAE;YACT,gBAAgB,EAAE,OAAO,CAAC;YAC1B,oBAAoB,EAAE,OAAO,CAAC;YAC9B,8BAA8B,EAAE,OAAO,CAAC;SACzC,CAAC;KACH,CAAC;IACF,YAAY,EAAE;QACZ,MAAM,EAAE;YACN,GAAG,EAAE,MAAM,EAAE,CAAC;SACf,CAAC;KACH,CAAC;IACF,QAAQ,EAAE;QACR,mBAAmB,EAAE;YACnB,UAAU,EAAE,MAAM,EAAE,CAAC;SACtB,CAAC;QACF,aAAa,EAAE;YACb,UAAU,EAAE,OAAO,CAAC;SACrB,CAAC;QACF,kBAAkB,EAAE,OAAO,CAAC;QAC5B,mBAAmB,EAAE,OAAO,CAAC;QAC7B,sBAAsB,EAAE,OAAO,CAAC;QAChC,cAAc,EAAE,OAAO,CAAC;QACxB,oBAAoB,CAAC,EAAE;YACrB,8BAA8B,EAAE,OAAO,CAAC;YACxC,2BAA2B,EAAE,MAAM,CAAC;SACrC,CAAC;KACH,CAAC;CACH;AAwDD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,oBAAoB,GAC5B,gBAAgB,CA+ElB;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,KAAK,CAAC,GACzC;IACD,GAAG,EAAE,gBAAgB,CAAC;IACtB,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAKA"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,iDACE,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE;QACR,QAAQ,EAAE;YACR,YAAY,EAAE,MAAM,CAAC;YACrB,aAAa,EAAE,OAAO,CAAC;SACxB,CAAC;QACF,cAAc,CAAC,EAAE;YACf,qBAAqB,EAAE,MAAM,CAAC;YAC9B,iBAAiB,EAAE,KAAK,CAAC;gBAAE,KAAK,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SAC9D,CAAC;QACF,QAAQ,CAAC,EAAE;YACT,gBAAgB,EAAE,OAAO,CAAC;YAC1B,oBAAoB,EAAE,OAAO,CAAC;YAC9B,8BAA8B,EAAE,OAAO,CAAC;SACzC,CAAC;KACH,CAAC;IACF,YAAY,EAAE;QACZ,MAAM,EAAE;YACN,GAAG,EAAE,MAAM,EAAE,CAAC;SACf,CAAC;KACH,CAAC;IACF,QAAQ,EAAE;QACR,mBAAmB,EAAE;YACnB,UAAU,EAAE,MAAM,EAAE,CAAC;SACtB,CAAC;QACF,aAAa,EAAE;YACb,UAAU,EAAE,OAAO,CAAC;SACrB,CAAC;QACF,kBAAkB,EAAE,OAAO,CAAC;QAC5B,mBAAmB,EAAE,OAAO,CAAC;QAC7B,sBAAsB,EAAE,OAAO,CAAC;QAChC,cAAc,EAAE,OAAO,CAAC;QACxB,oBAAoB,CAAC,EAAE;YACrB,8BAA8B,EAAE,OAAO,CAAC;YACxC,2BAA2B,EAAE,MAAM,CAAC;SACrC,CAAC;KACH,CAAC;CACH;AAwDD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,oBAAoB,GAC5B,gBAAgB,CA+ElB;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,KAAK,CAAC,GACzC;IACD,GAAG,EAAE,gBAAgB,CAAC;IACtB,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAKA;AAED,kDAAkD;AAClD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE;IAAE,GAAG,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,EACvD,GAAG,GAAE,KAAK,GAAG,MAAM,GAAG,MAAe,GACpC,aAAa,CAAC;IACf,IAAI,EAAE,mBAAmB,GAAG,oBAAoB,CAAC;IACjD,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAkBD"}

package/dist/channels/slack/manifest.js

@@ -134,3 +134,20 @@ export function buildSlackManifestPair(options) {
         prod: buildSlackManifest(Object.assign(Object.assign({}, options), { env: "prod" })),
     };
 }
+/** Relative names under `.agent-serve/slack/`. */
+export function slackManifestFileEntries(pair, env = "both") {
+    const files = [];
+    if (env === "dev" || env === "both") {
+        files.push({
+            name: "manifest.dev.json",
+            contents: `${JSON.stringify(pair.dev, null, 2)}\n`,
+        });
+    }
+    if (env === "prod" || env === "both") {
+        files.push({
+            name: "manifest.prod.json",
+            contents: `${JSON.stringify(pair.prod, null, 2)}\n`,
+        });
+    }
+    return files;
+}

package/dist/channels/slack/setup.d.ts

@@ -2,7 +2,32 @@
  * Slack setup guide printed by `agent-serve slack setup`.
  *
  * Two products: Cursor-hosted (`cursorAccount`) vs a dedicated Socket
- * Mode app via `slack create` (dashboard wizard).
+ * Mode app via `slack create` (dashboard wizard). `slack init --manual`
+ * is the unmanaged paste-at-api.slack.com path. {@link SLACK_SETUP_PHASES}
+ * is that checklist; its ids key `.agent-serve/slack/setup-status.json`.
  */
+export interface SlackSetupPhase {
+    id: string;
+    actor: "agent" | "human";
+    title: string;
+    steps: string[];
+}
+export declare const SLACK_SETUP_PHASES: SlackSetupPhase[];
+/** Seed `.agent-serve/slack/setup-status.json` after `slack init --manual`. */
+export declare function initialSlackSetupStatus(options: {
+    envPrefix: string | undefined;
+    envKeys: {
+        bot: string;
+        app: string;
+    };
+}): {
+    updatedAt: string;
+    envPrefix: string | null;
+    envKeys: {
+        bot: string;
+        app: string;
+    };
+    phases: Record<string, boolean>;
+};
 export declare function formatSlackSetupGuide(): string;
 //# sourceMappingURL=setup.d.ts.map

package/dist/channels/slack/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/setup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,qBAAqB,IAAI,MAAM,CAyB9C"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/setup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EA4D/C,CAAC;AAEF,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC,GAAG;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAUA;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAkC9C"}

package/dist/channels/slack/setup.js

@@ -2,31 +2,113 @@
  * Slack setup guide printed by `agent-serve slack setup`.
  *
  * Two products: Cursor-hosted (`cursorAccount`) vs a dedicated Socket
- * Mode app via `slack create` (dashboard wizard).
+ * Mode app via `slack create` (dashboard wizard). `slack init --manual`
+ * is the unmanaged paste-at-api.slack.com path. {@link SLACK_SETUP_PHASES}
+ * is that checklist; its ids key `.agent-serve/slack/setup-status.json`.
  */
+export const SLACK_SETUP_PHASES = [
+    {
+        id: "generate",
+        actor: "agent",
+        title: "Generate channel + manifests",
+        steps: [
+            "agent-serve slack init --manual --dir . --name My Agent",
+            "Manifests default to Socket Mode (no public Request URL).",
+        ],
+    },
+    {
+        id: "createApps",
+        actor: "human",
+        title: "Create two Slack apps from manifests",
+        steps: [
+            "Open https://api.slack.com/apps -> Create New App from a manifest",
+            "Paste .agent-serve/slack/manifest.dev.json -> create the *dev* app",
+            "Repeat with manifest.prod.json for the *prod* app",
+        ],
+    },
+    {
+        id: "install",
+        actor: "human",
+        title: "Install + mint App-Level Token",
+        steps: [
+            "Install to Workspace; copy Bot User OAuth Token (xoxb-...)",
+            "App-Level Tokens: create token with connections:write; copy xapp-...",
+        ],
+    },
+    {
+        id: "env",
+        actor: "agent",
+        title: "Wire environment",
+        steps: [
+            "Write per-agent tokens into .env.local (see .agent-serve/slack/env.example)",
+            "Multi-agent: <PREFIX>_SLACK_BOT_TOKEN + <PREFIX>_SLACK_APP_TOKEN",
+            "Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN (--no-prefix)",
+            "agent-serve slack doctor --prefix <PREFIX>",
+        ],
+    },
+    {
+        id: "serve",
+        actor: "agent",
+        title: "Serve",
+        steps: [
+            "agent-serve serve --dir . --dev",
+            "Confirm log: [agent-sdk/slack] Socket Mode connected",
+        ],
+    },
+    {
+        id: "smoke",
+        actor: "human",
+        title: "Smoke test",
+        steps: [
+            "Invite the bot to a channel",
+            "@mention it or DM it",
+            "Confirm logs: inbound → session start → reply delivered",
+            "Confirm streaming reply and rotating status",
+        ],
+    },
+];
+/** Seed `.agent-serve/slack/setup-status.json` after `slack init --manual`. */
+export function initialSlackSetupStatus(options) {
+    var _a;
+    var _b;
+    const completed = (_a = SLACK_SETUP_PHASES[0]) === null || _a === void 0 ? void 0 : _a.id;
+    return {
+        updatedAt: new Date().toISOString(),
+        envPrefix: (_b = options.envPrefix) !== null && _b !== void 0 ? _b : null,
+        envKeys: options.envKeys,
+        phases: Object.fromEntries(SLACK_SETUP_PHASES.map((phase) => [phase.id, phase.id === completed])),
+    };
+}
 export function formatSlackSetupGuide() {
-    return `agent-serve — Slack setup
-
-Two products. Pick one.
-
-  A) Cursor-hosted (recommended default, zero Slack admin):
-     slackChannel({ cursorAccount: true, agentName: "MyAgent" })
-     Sign in (agent-serve login / CURSOR_API_KEY), serve, then mention
-     "@Cursor MyAgent ..." in the linked workspace. No app, no tokens.
-
-  B) Dedicated Slack app (Socket Mode):
-     agent-serve slack create --dir .
-     Opens the signed-in Cursor dashboard wizard. Finish Slack consent
-     and the bot name there. The CLI writes tokens into .env.local.
-     Use this when you need your own bot user, channel watching
-     (engagement.channelPosts), or approval buttons.
-
-Do not paste a manifest at api.slack.com. \`slack init\` is removed.
-
-Then:
-  - agent-serve serve --dir . --dev
-  - Invite the bot (Path B) or mention @Cursor <name> (Path A)
-
-Skill: packages/agent-serve/skills/setup-slack/SKILL.md
-`;
+    const lines = [
+        "agent-serve — Slack setup",
+        "",
+        "Two products. Pick one.",
+        "",
+        "  A) Cursor-hosted (recommended default, zero Slack admin):",
+        '     slackChannel({ cursorAccount: true, agentName: "MyAgent" })',
+        "     Sign in (agent-serve login / CURSOR_API_KEY), serve, then mention",
+        '     "@Cursor MyAgent ..." in the linked workspace. No app, no tokens.',
+        "  B) Dedicated Slack app (Socket Mode) via the dashboard wizard:",
+        "     agent-serve slack create --dir .",
+        "     Finish Slack consent and the bot name there. The CLI writes",
+        "     tokens into .env.local. Use this when you need your own bot",
+        "     user, channel watching, or approval buttons.",
+        "",
+        "Manual Slack app: `slack init --manual`. Phases below.",
+        "Goal: importable dev + prod Slack apps over Socket Mode (no public URL).",
+        "App-Level Token (xapp-...) + Bot Token (xoxb-...) required.",
+        "",
+    ];
+    for (const [index, phase] of SLACK_SETUP_PHASES.entries()) {
+        lines.push(`## Phase ${index} — ${phase.title} (${phase.actor})`);
+        for (const step of phase.steps) {
+            lines.push(`  - ${step}`);
+        }
+        lines.push("");
+    }
+    lines.push("Status file: .agent-serve/slack/setup-status.json");
+    lines.push("Skill (Cursor): packages/agent-serve/skills/setup-slack/SKILL.md");
+    lines.push("");
+    return lines.join("\n");
 }

package/dist/docs/404.html

@@ -6,17 +6,17 @@
     <title>404 | Agent SDK</title>
     <meta name="description" content="Not Found">
     <meta name="generator" content="VitePress v1.6.4">
-    <link rel="preload stylesheet" href="/docs/assets/style.CK3hwt6q.css" as="style">
+    <link rel="preload stylesheet" href="/docs/assets/style.kTsvp4pE.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
     
-    <script type="module" src="/docs/assets/app.Cbeq6FOy.js"></script>
+    <script type="module" src="/docs/assets/app.DAKcDclS.js"></script>
     <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
   </head>
   <body>
     <div id="app"></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_github.md\":\"B8QKtIpw\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"D2nTRu9M\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"COeoSkcF\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"DHkkvcEZ\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"CGKfz_Yj\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"kJfJAP2m\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"D8NQ389l\",\"templates_triage.md\":\"CConZt1z\",\"troubleshooting.md\":\"C6n3wCr6\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_github.md\":\"B8QKtIpw\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"DP4H75WP\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"COeoSkcF\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"DHkkvcEZ\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"-V6J7Cl8\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"kJfJAP2m\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"D8NQ389l\",\"templates_triage.md\":\"CConZt1z\",\"troubleshooting.md\":\"CuVztCKs\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>