@cursor/july 0.1.1

package/dist/internal/cli-slack.js

@@ -0,0 +1,144 @@
+/**
+ * `agent-serve slack …` CLI — manifests, setup, doctor (Socket Mode).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join, resolve as resolvePath } from "node:path";
+import { buildSlackManifestPair, formatSlackSetupGuide, initSlackChannel, runSlackDoctor, } from "../channels/slack/index.js";
+const SLACK_HELP = `agent-serve slack — Slack channel pack helpers (Socket Mode)
+
+Usage:
+  agent-serve slack setup
+  agent-serve slack init      [--dir .] [--name NAME] [--prefix PREFIX | --no-prefix]
+                                [--channel-posts]
+  agent-serve slack manifest --env dev|prod|both [--dir .] [--name NAME]
+                                [--print]
+  agent-serve slack doctor [--prefix PREFIX] [--json]
+
+Env tokens:
+  single agent:  SLACK_BOT_TOKEN + SLACK_APP_TOKEN
+  multi-agent:   <PREFIX>_SLACK_BOT_TOKEN + <PREFIX>_SLACK_APP_TOKEN
+                 (init defaults PREFIX from the directory name)
+
+See also: skills/setup-slack/SKILL.md
+`;
+export function cmdSlack(subcommand, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        switch (subcommand) {
+            case undefined:
+            case "help":
+            case "--help":
+            case "-h":
+                process.stdout.write(SLACK_HELP);
+                return subcommand === undefined ? 1 : 0;
+            case "setup":
+                process.stdout.write(formatSlackSetupGuide());
+                return 0;
+            case "init":
+                return cmdSlackInit(options);
+            case "manifest":
+                return runManifest(options);
+            case "doctor":
+                return runDoctor(options);
+            default:
+                process.stderr.write(`Unknown slack subcommand: ${subcommand}\n`);
+                process.stdout.write(SLACK_HELP);
+                return 1;
+        }
+    });
+}
+function cmdSlackInit(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const dir = resolvePath(options.dir);
+        try {
+            const result = yield initSlackChannel(Object.assign(Object.assign(Object.assign({ dir }, (options.name === undefined ? {} : { name: options.name })), (options.noPrefix === true
+                ? { envPrefix: "" }
+                : options.prefix === undefined
+                    ? {}
+                    : { envPrefix: options.prefix })), (options.channelPosts === true ? { channelPosts: true } : {})));
+            process.stdout.write(`${JSON.stringify({
+                ok: true,
+                directory: result.rootDir,
+                created: result.files,
+                envPrefix: (_a = result.envPrefix) !== null && _a !== void 0 ? _a : null,
+                envKeys: result.envKeys,
+                next: [
+                    "Open https://api.slack.com/apps → Create from manifest",
+                    "Import .agent-serve/slack/manifest.dev.json (then prod)",
+                    `Install apps; set ${result.envKeys.bot} + ${result.envKeys.app}`,
+                    result.envPrefix === undefined
+                        ? "agent-serve slack doctor"
+                        : `agent-serve slack doctor --prefix ${result.envPrefix}`,
+                    "agent-serve serve --dir . --dev",
+                    "agent-serve slack setup",
+                ],
+            }, null, 2)}\n`);
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    });
+}
+function runManifest(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const env = (_a = options.env) !== null && _a !== void 0 ? _a : "both";
+        const dir = resolvePath(options.dir);
+        const name = (_b = options.name) !== null && _b !== void 0 ? _b : basename(dir);
+        const pair = buildSlackManifestPair(Object.assign({ name }, (options.channelPosts === true ? { channelPosts: true } : {})));
+        if (options.print) {
+            if (env === "dev" || env === "both") {
+                process.stdout.write(`${JSON.stringify(pair.dev, null, 2)}\n`);
+            }
+            if (env === "prod" || env === "both") {
+                if (env === "both") {
+                    process.stdout.write("--- prod ---\n");
+                }
+                process.stdout.write(`${JSON.stringify(pair.prod, null, 2)}\n`);
+            }
+            return 0;
+        }
+        const outDir = join(dir, ".agent-serve/slack");
+        yield mkdir(outDir, { recursive: true });
+        const written = [];
+        if (env === "dev" || env === "both") {
+            const path = join(outDir, "manifest.dev.json");
+            yield writeFile(path, `${JSON.stringify(pair.dev, null, 2)}\n`);
+            written.push(path);
+        }
+        if (env === "prod" || env === "both") {
+            const path = join(outDir, "manifest.prod.json");
+            yield writeFile(path, `${JSON.stringify(pair.prod, null, 2)}\n`);
+            written.push(path);
+        }
+        process.stdout.write(`${JSON.stringify({ ok: true, written }, null, 2)}\n`);
+        return 0;
+    });
+}
+function runDoctor(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const result = yield runSlackDoctor(options.prefix === undefined ? {} : { envPrefix: options.prefix });
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(`env: ${result.envKeys.bot} / ${result.envKeys.app}\n`);
+            for (const check of result.checks) {
+                process.stdout.write(`${check.ok ? "ok" : "!!"}  ${check.id}: ${check.message}\n`);
+            }
+            process.stdout.write(result.ok ? "doctor: pass\n" : "doctor: fail\n");
+        }
+        return result.ok ? 0 : 1;
+    });
+}

package/dist/internal/cloud-merge.d.ts

@@ -0,0 +1,23 @@
+import type { AgentCloudOptions, AgentRuntime } from "../types.js";
+/**
+ * Merge a per-session cloud override over the agent's static cloud config.
+ *
+ * Session-scoped `repos` / `env` / scalar flags win (so a channel can point
+ * a cloud agent at a specific PR per session), and `envVars` are deep-merged
+ * with the override taking precedence per key. Returns the defined side when
+ * only one is present. Named fields keep base/override precedence explicit
+ * at every call site.
+ */
+export declare function mergeCloudOptions(args: {
+    base: AgentCloudOptions | undefined;
+    override: AgentCloudOptions | undefined;
+}): AgentCloudOptions | undefined;
+/**
+ * Session turn runtime: a per-session `cloud` attach forces cloud even when
+ * the agent defaults to local (chat server tools + Drive handoff).
+ */
+export declare function resolveSessionRuntime(args: {
+    agentRuntime: AgentRuntime;
+    cloudOverride: AgentCloudOptions | undefined;
+}): AgentRuntime;
+//# sourceMappingURL=cloud-merge.d.ts.map

package/dist/internal/cloud-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-merge.d.ts","sourceRoot":"","sources":["../../src/internal/cloud-merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEnE;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACzC,GAAG,iBAAiB,GAAG,SAAS,CAehC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC9C,GAAG,YAAY,CAEf"}

package/dist/internal/cloud-merge.js

@@ -0,0 +1,28 @@
+/**
+ * Merge a per-session cloud override over the agent's static cloud config.
+ *
+ * Session-scoped `repos` / `env` / scalar flags win (so a channel can point
+ * a cloud agent at a specific PR per session), and `envVars` are deep-merged
+ * with the override taking precedence per key. Returns the defined side when
+ * only one is present. Named fields keep base/override precedence explicit
+ * at every call site.
+ */
+export function mergeCloudOptions(args) {
+    const { base, override } = args;
+    if (base === undefined) {
+        return override;
+    }
+    if (override === undefined) {
+        return base;
+    }
+    return Object.assign(Object.assign(Object.assign({}, base), override), (base.envVars !== undefined || override.envVars !== undefined
+        ? { envVars: Object.assign(Object.assign({}, base.envVars), override.envVars) }
+        : {}));
+}
+/**
+ * Session turn runtime: a per-session `cloud` attach forces cloud even when
+ * the agent defaults to local (chat server tools + Drive handoff).
+ */
+export function resolveSessionRuntime(args) {
+    return args.cloudOverride !== undefined ? "cloud" : args.agentRuntime;
+}

package/dist/internal/cron.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cron helpers for schedules and reminders. Thin wrapper around `croner`
+ * (same package as backend/server) so we keep a stable `parseCron` /
+ * `isValidCron` surface for discovery and runners.
+ *
+ * Standard 5-field expressions (minute hour day-of-month month day-of-week),
+ * evaluated in UTC with minute granularity.
+ */
+export interface CronExpression {
+    readonly source: string;
+    matches(date: Date): boolean;
+    /** Next fire strictly after `after` (defaults to now). */
+    nextFire(after?: Date): Date;
+}
+export declare function parseCron(source: string): CronExpression;
+export declare function isValidCron(source: string): boolean;
+//# sourceMappingURL=cron.d.ts.map

package/dist/internal/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../../src/internal/cron.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC9B;AA4BD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAwBxD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOnD"}

package/dist/internal/cron.js

@@ -0,0 +1,60 @@
+/**
+ * Cron helpers for schedules and reminders. Thin wrapper around `croner`
+ * (same package as backend/server) so we keep a stable `parseCron` /
+ * `isValidCron` surface for discovery and runners.
+ *
+ * Standard 5-field expressions (minute hour day-of-month month day-of-week),
+ * evaluated in UTC with minute granularity.
+ */
+import { Cron } from "croner";
+function createCroner(source) {
+    try {
+        return new Cron(source, {
+            timezone: "UTC",
+            // Schedules/reminders are 5-field; reject 6-field seconds forms.
+            legacyMode: true,
+        });
+    }
+    catch (error) {
+        throw new Error(`Invalid cron expression "${source}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * True when `date`'s UTC minute is a fire time for the expression.
+ * Implemented via croner's nextRun from one second before the minute floor.
+ */
+function matchesCron(cron, date) {
+    const floorMs = Math.floor(date.getTime() / 60000) * 60000;
+    const next = cron.nextRun(new Date(floorMs - 1000));
+    return next !== null && next.getTime() === floorMs;
+}
+export function parseCron(source) {
+    const trimmed = source.trim();
+    const parts = trimmed.split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error(`Invalid cron expression "${source}": expected 5 fields, got ${parts.length}`);
+    }
+    const cron = createCroner(trimmed);
+    return {
+        source: trimmed,
+        matches(date) {
+            return matchesCron(cron, date);
+        },
+        nextFire(after = new Date()) {
+            const next = cron.nextRun(after);
+            if (next === null) {
+                throw new Error(`Could not find next fire for cron "${trimmed}" after ${after.toISOString()}`);
+            }
+            return next;
+        },
+    };
+}
+export function isValidCron(source) {
+    try {
+        parseCron(source);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}

package/dist/internal/cursor/account-mcp.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The Cursor account MCP bridge: `defineConnection({ cursorAccount: true })`
+ * resolved for local turns.
+ *
+ * The serve host mounts one loopback-only streamable-HTTP MCP route per
+ * authored account MCP connection (`<base>/v1/cursor-account/<name>/mcp`,
+ * guarded by a per-boot bearer secret). The bridge lists and executes the
+ * account's connector tools through the Cursor backend
+ * (`DashboardService.ListSandMcpTools` / `ExecuteSandMcpTool`), which owns
+ * the OAuth credentials — **raw MCP tokens never enter this process**.
+ *
+ * Cloud-runtime turns reach the same bridge through the serve `publicUrl`
+ * (so `servers` filters apply there too); without one they omit the bridge
+ * and fall back to the account's natively hydrated connectors.
+ */
+import type { AgentProject, AuthPolicy } from "../../types.js";
+import type { EngineResolvedConnection } from "../session-engine.js";
+import type { CursorBackendClient } from "./backend-client.js";
+export interface CursorAccountConnectionRef {
+    /** Connection (MCP server) name — the filename under `agent/mcp-connections/`. */
+    name: string;
+    /** Connector-name filter, or undefined for every connected server. */
+    servers?: string[];
+}
+/**
+ * Collect `cursorAccount` connections across `mounts`, grouped by mount
+ * slug. Purely structural — per-connector validation happens live against
+ * the account (see {@link CursorAccountMcpBridge.logPreflight}).
+ */
+export declare function collectCursorAccountConnections(mounts: Array<{
+    slug: string;
+    project: AgentProject;
+}>): Map<string, CursorAccountConnectionRef[]>;
+/** Bridge mount path for one account MCP connection, relative to the agent base. */
+export declare function cursorAccountMcpPath(connectionName: string): string;
+/**
+ * Resolve account refs to engine connections once the server is listening.
+ * Local turns and host-side `ctx.host.mcp` reach the loopback bridge with
+ * the per-boot secret. When `publicUrl` is configured, cloud turns use the
+ * same bridge route so `servers` filters apply there too.
+ */
+export declare function resolveCursorAccountConnections(args: {
+    refs: CursorAccountConnectionRef[];
+    /** Serve bind URL (`http://<host>:<port>`). */
+    serverUrl: string;
+    basePath: string;
+    bridgeSecret: string;
+    publicUrl?: string;
+}): EngineResolvedConnection[];
+export declare class CursorAccountMcpBridge {
+    /** Per-boot shared secret; resolved connections carry it as a bearer. */
+    readonly secret: string;
+    private readonly client;
+    private readonly logger;
+    private readonly secretPolicy;
+    private readonly allowRemoteCallers;
+    private readonly catalogs;
+    constructor(args: {
+        client: CursorBackendClient;
+        logger?: (line: string) => void;
+        /**
+         * Admit non-loopback callers presenting the secret. Only set when the
+         * serve host configured a `publicUrl` (cloud turns reach the bridge
+         * through it); otherwise the bridge stays strictly loopback-only.
+         */
+        allowRemoteCallers?: boolean;
+    });
+    /**
+     * Route auth for the bridge: the per-boot bearer secret, from a loopback
+     * TCP peer — or from anywhere when the serve host exposed the bridge via
+     * `publicUrl` (cloud turns arrive through that ingress with the secret).
+     */
+    authPolicy(): AuthPolicy;
+    /**
+     * Handle one streamable-HTTP MCP request for the connection described by
+     * `ref` (stateless: fresh server per POST, like the per-agent endpoint).
+     */
+    handle(request: Request, ref: CursorAccountConnectionRef): Promise<Response>;
+    /**
+     * Startup DX: log the account's connector statuses for `refs` without
+     * blocking serve startup. Surfaces "needsAuth" connectors (authorize in
+     * Cursor) and filters that matched nothing (typo'd connector names).
+     */
+    logPreflight(refs: CursorAccountConnectionRef[]): void;
+    private buildServer;
+    /** Resolve a tool by exposed name, refreshing once when it is unknown. */
+    private findTool;
+    /**
+     * Fetch (or join) the catalog for `ref`'s server filter. Staleness and
+     * joining are decided synchronously: in-flight entries always join their
+     * promise; fresh entries use {@link CatalogEntry.freshAtMs} for TTL.
+     */
+    private getCatalog;
+}
+//# sourceMappingURL=account-mcp.d.ts.map

package/dist/internal/cursor/account-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-mcp.d.ts","sourceRoot":"","sources":["../../../src/internal/cursor/account-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAI/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAgB7B,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,GACrD,GAAG,CAAC,MAAM,EAAE,0BAA0B,EAAE,CAAC,CAoB3C;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACpD,IAAI,EAAE,0BAA0B,EAAE,CAAC;IACnC,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,wBAAwB,EAAE,CAkB7B;AAiCD,qBAAa,sBAAsB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAE5D,YAAY,IAAI,EAAE;QAChB,MAAM,EAAE,mBAAmB,CAAC;QAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAChC;;;;WAIG;QACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,EAKA;IAED;;;;OAIG;IACH,UAAU,IAAI,UAAU,CAgBvB;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,0BAA0B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAO3E;IAED;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,0BAA0B,EAAE,GAAG,IAAI,CAwCrD;IAED,OAAO,CAAC,WAAW;IAkEnB,0EAA0E;YAC5D,QAAQ;IAatB;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAwCnB"}