@cursor/july 0.1.1

package/dist/internal/cursor-slack-relay.js

@@ -0,0 +1,171 @@
+/**
+ * Pulls `/v0/slack-events` into agent-serve: register the mounted
+ * cursor-account Slack agents (name + icon) with the Cursor backend, then
+ * long-poll routed events with a durable offset under
+ * `<stateDir>/offset.json` and dispatch each to the agent it addresses.
+ * Outbound Slack Web API calls are proxied through `POST /v0/slack-events/api`
+ * via a per-agent {@link SlackApiTransport} binding.
+ *
+ * Same lifecycle rules as the SCM relay (`cursor-event-relay.ts`):
+ * registration-gated consumption, heartbeat re-registration, durable
+ * consumer id, at-least-once dispatch with client-owned offsets.
+ */
+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 { CursorRelayCore, describeRelayError, } from "./cursor-relay-core.js";
+/** Human-readable log fragment for one relayed Slack event. */
+export function formatCursorSlackEventLog(envelope) {
+    var _a;
+    const received = new Date(envelope.receivedAtMs).toISOString();
+    return `${envelope.eventName} → ${envelope.agentName} (${envelope.matchedBy}) in ${envelope.channelId}/${envelope.threadTs} received=${received} (${(_a = envelope.eventId) !== null && _a !== void 0 ? _a : "no event id"})`;
+}
+/**
+ * Build the backend proxy caller one agent's {@link SlackApiTransport}
+ * binds to. Returns Slack-shaped `{ ok: false, error }` bodies on transport
+ * failures so channel soft-fail paths behave exactly like direct Web API
+ * callers.
+ */
+export function createCursorSlackApiCaller(args) {
+    var _a;
+    const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+    const url = `${args.baseUrl.replace(/\/+$/, "")}/v0/slack-events/api`;
+    return (method, callArgs) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        try {
+            const response = yield fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${args.apiKey}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    method,
+                    arguments: callArgs,
+                    agentName: args.agentName,
+                    consumerId: args.consumerId,
+                }),
+            });
+            const body = (yield response.json().catch(() => undefined));
+            if (body !== undefined && typeof body === "object") {
+                if (!response.ok && body.ok === undefined) {
+                    const error = typeof body.error === "string"
+                        ? body.error
+                        : `cursor_backend_http_${response.status}`;
+                    return { ok: false, error };
+                }
+                return body;
+            }
+            return {
+                ok: false,
+                error: `cursor_backend_http_${response.status}`,
+            };
+        }
+        catch (error) {
+            (_a = args.logger) === null || _a === void 0 ? void 0 : _a.call(args, `[agent-serve] cursor-slack: ${method} proxy call failed: ${describeRelayError(error)}`);
+            return { ok: false, error: "cursor_backend_unreachable" };
+        }
+    });
+}
+/**
+ * Cursor Slack relay: a thin {@link CursorRelayCore} adapter. Keeps the same
+ * `new CursorSlackRelay(options)` surface with `.resolveConsumerId()`,
+ * `.start()`, and `.stop()` (the server binds outbound transports with the
+ * resolved consumer id before starting).
+ */
+export class CursorSlackRelay {
+    constructor(options) {
+        this.options = options;
+        /**
+         * Agent names (lowercased) the server confirmed for THIS consumer. The
+         * stream is shared with sibling consumers of the same principal, so only
+         * events for these agents (and this consumer id) may dispatch.
+         */
+        this.subscribedAgents = new Set();
+        this.consumerId = "";
+        const adapter = {
+            logPrefix: "cursor-slack",
+            subscribePath: "/v0/slack-events/subscriptions",
+            pollPath: "/v0/slack-events",
+            buildRegistrationBody: (consumerId) => {
+                this.consumerId = consumerId;
+                return {
+                    consumerId,
+                    // Optional fields may be undefined — JSON.stringify drops them
+                    // from the registration body.
+                    agents: this.options.agents.map((agent) => ({
+                        name: agent.name,
+                        iconUrl: agent.iconUrl,
+                        iconEmoji: agent.iconEmoji,
+                    })),
+                };
+            },
+            applyRegistrationResponse: (json) => {
+                var _a, _b, _c;
+                const result = json;
+                const agentStatuses = (_a = result.agents) !== null && _a !== void 0 ? _a : [];
+                this.subscribedAgents = new Set(agentStatuses
+                    .filter((status) => status.isSubscribed)
+                    .map((status) => status.name.toLowerCase()));
+                const failures = [
+                    ...((_b = result.workspaces) !== null && _b !== void 0 ? _b : [])
+                        .filter((workspace) => !workspace.isSubscribed)
+                        .map((workspace) => { var _a; return `workspace ${workspace.slackTeamId}: ${(_a = workspace.detail) !== null && _a !== void 0 ? _a : "not subscribed"}`; }),
+                    ...agentStatuses
+                        .filter((status) => !status.isSubscribed)
+                        .map((status) => { var _a; return `agent ${status.name}: ${(_a = status.detail) !== null && _a !== void 0 ? _a : "rejected"}`; }),
+                ];
+                if (failures.length > 0) {
+                    return failures;
+                }
+                const workspaceIds = ((_c = result.workspaces) !== null && _c !== void 0 ? _c : [])
+                    .filter((workspace) => workspace.isSubscribed)
+                    .map((workspace) => workspace.slackTeamId);
+                return [
+                    `registered ${[...this.subscribedAgents].join(", ")} on Slack workspace ${workspaceIds.join(", ")}`,
+                ];
+            },
+            shouldDispatch: (event) => this.shouldDispatch(event),
+            dispatch: (event) => this.options.dispatch(event),
+        };
+        this.core = new CursorRelayCore(Object.assign(Object.assign({ baseUrl: options.baseUrl, apiKey: options.apiKey, stateDir: options.stateDir, adapter, logger: options.logger }, (options.fetchImpl === undefined
+            ? {}
+            : { fetchImpl: options.fetchImpl })), (options.pollWaitMs === undefined
+            ? {}
+            : { pollWaitMs: options.pollWaitMs })));
+    }
+    /**
+     * Resolve the durable consumer id before starting, so transports can bind
+     * with it. Also used by tests.
+     */
+    resolveConsumerId() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.consumerId = yield this.core.resolveConsumerId();
+            return this.consumerId;
+        });
+    }
+    /**
+     * Whether a relayed event belongs to THIS consumer: the backend stamps
+     * each envelope with the registering consumer id and agent.
+     */
+    shouldDispatch(event) {
+        if (event.consumerId !== this.consumerId) {
+            return false;
+        }
+        return this.subscribedAgents.has(event.agentName.toLowerCase());
+    }
+    start() {
+        this.core.start();
+    }
+    stop() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.core.stop();
+        });
+    }
+}

package/dist/internal/describe-error.d.ts

@@ -0,0 +1,3 @@
+/** Stable string for logging / HTTP error bodies. */
+export declare function describeError(error: unknown): string;
+//# sourceMappingURL=describe-error.d.ts.map

package/dist/internal/describe-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../../src/internal/describe-error.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/internal/describe-error.js

@@ -0,0 +1,4 @@
+/** Stable string for logging / HTTP error bodies. */
+export function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/internal/dev-mode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Process-wide dev-mode flag.
+ *
+ * Channels are constructed at module import time (during discovery), before a
+ * channel factory like `githubChannel()` ever sees the server's `--dev` flag.
+ * `serve()` sets this flag *before* discovery so those factories can relax
+ * dev-only defaults (e.g. the GitHub channel admitting loopback-forwarded
+ * webhook deliveries without a signing secret). It never affects prod: outside
+ * `--dev` the flag stays false and strict defaults apply.
+ */
+export declare function setDevMode(value: boolean): void;
+export declare function isDevMode(): boolean;
+//# sourceMappingURL=dev-mode.d.ts.map

package/dist/internal/dev-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-mode.d.ts","sourceRoot":"","sources":["../../src/internal/dev-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE/C;AAED,wBAAgB,SAAS,IAAI,OAAO,CAEnC"}

package/dist/internal/dev-mode.js

@@ -0,0 +1,17 @@
+/**
+ * Process-wide dev-mode flag.
+ *
+ * Channels are constructed at module import time (during discovery), before a
+ * channel factory like `githubChannel()` ever sees the server's `--dev` flag.
+ * `serve()` sets this flag *before* discovery so those factories can relax
+ * dev-only defaults (e.g. the GitHub channel admitting loopback-forwarded
+ * webhook deliveries without a signing secret). It never affects prod: outside
+ * `--dev` the flag stays false and strict defaults apply.
+ */
+let devMode = false;
+export function setDevMode(value) {
+    devMode = value;
+}
+export function isDevMode() {
+    return devMode;
+}

package/dist/internal/discovery.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Filesystem discovery: walks a project's `agent/` directory and compiles
+ * the authored files (markdown and TypeScript) into an {@link AgentProject}
+ * manifest. Identity comes from the path — a tool at `agent/tools/foo.ts`
+ * is named `foo`, a subagent at `agent/subagents/researcher/` is named
+ * `researcher` — so no definition carries a `name` field.
+ */
+import { type AgentProject, type AgentProjectInfo, type Diagnostic } from "../types.js";
+export interface LoadAgentProjectOptions {
+    /** Override the module loader (embedders / tests). */
+    importModule?: (absolutePath: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * True when `dir` looks like an agent project root: it has a nested `agent/`
+ * directory, or flat-layout markers (`agent.ts` / `instructions.md`) directly
+ * inside it.
+ */
+export declare function isAgentProjectDir(dir: string): Promise<boolean>;
+/**
+ * Discover the agent projects directly under `rootDir` (one level deep):
+ * each immediate child directory that is itself an agent project becomes a
+ * mounted agent, keyed by a slug derived from its directory name. Used for
+ * multi-agent serving, where one server hosts many agents under
+ * `/<slug>/...`. Throws when no child projects are found.
+ */
+export declare function loadAgentProjects(rootDir: string, options?: LoadAgentProjectOptions): Promise<Array<{
+    slug: string;
+    project: AgentProject;
+}>>;
+/**
+ * Resolve mounts for `serve` / CLI. Defaults to multi-agent layout:
+ * - `mode: "single"` — one agent at `/v1/*` (empty slug).
+ * - otherwise, if `rootDir` is itself an agent project — one agent under
+ *   `/<dirname>/...`.
+ * - otherwise, every immediate child agent project under `/<slug>/...`.
+ */
+export declare function resolveAgentMounts(rootDir: string, options?: LoadAgentProjectOptions & {
+    mode?: "single" | "multi";
+}): Promise<Array<{
+    slug: string;
+    project: AgentProject;
+}>>;
+/** URL path segments reserved by the server; agents cannot use them as slugs. */
+export declare const RESERVED_SLUGS: Set<string>;
+export declare function loadAgentProject(dir: string, options?: LoadAgentProjectOptions): Promise<AgentProject>;
+/** True when the project has diagnostics that must block serving. */
+export declare function hasErrorDiagnostics(project: AgentProject): boolean;
+export declare function formatDiagnostics(diagnostics: Diagnostic[]): string;
+/**
+ * Advertise the first non-empty, non-code-fence line of the body, with any
+ * leading `#`, `>`, `*`, or `-` markers stripped.
+ */
+export declare function deriveSkillDescription(markdown: string): string | undefined;
+export declare function projectInfo(project: AgentProject): AgentProjectInfo;
+//# sourceMappingURL=discovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/internal/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAKrB,KAAK,UAAU,EAmBhB,MAAM,aAAa,CAAC;AAarB,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAmBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAiCzD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAAuB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAgBzD;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAIrC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CA4DvB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAElE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAOnE;AAwgBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAujBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CA6HnE"}