@cursor/july 0.1.101 → 0.1.103

package/src/internal/channel-dispatch.ts

@@ -0,0 +1,160 @@
+import type {
+  ChannelHandlerArgs,
+  ChannelSession,
+  SendMessageFn,
+} from "../types.js";
+import { isDeferredChannelSession } from "./deferred-channel-session.js";
+
+/**
+ * What a webhook dispatch decided. Hosted admission reads it off the
+ * Response without parsing the body.
+ */
+export type DispatchOutcome = "skip" | "send" | "task";
+
+const outcomeByResponse = new WeakMap<Response, DispatchOutcome>();
+
+export function tagOutcome(
+  response: Response,
+  outcome: DispatchOutcome
+): Response {
+  outcomeByResponse.set(response, outcome);
+  return response;
+}
+
+export function dispatchOutcome(
+  response: Response
+): DispatchOutcome | undefined {
+  return outcomeByResponse.get(response);
+}
+
+export function skipped(
+  reason: string,
+  extra: Record<string, unknown> = {}
+): Response {
+  return tagOutcome(
+    Response.json({ ok: true, skipped: true, reason, ...extra }),
+    "skip"
+  );
+}
+
+/** 202 for a turn whose send completes after the response flushes. */
+export function acknowledgeTurn(): Response {
+  return tagOutcome(
+    Response.json(
+      { ok: true, dispatched: true, mode: "turn" },
+      { status: 202 }
+    ),
+    "send"
+  );
+}
+
+/**
+ * Report the session a send returned. Hosted admission returns a deferred
+ * session: it captured the send and the control plane allocates the real
+ * session after acknowledgement, so there is nothing to report yet.
+ */
+export function turnStarted(session: ChannelSession): Response {
+  if (isDeferredChannelSession(session)) {
+    return acknowledgeTurn();
+  }
+  return tagOutcome(
+    Response.json({
+      ok: true,
+      sessionId: session.id,
+      isNew: session.isNew,
+      continuationToken: session.continuationToken,
+    }),
+    "send"
+  );
+}
+
+interface TaskDispatch {
+  task: (args: {
+    send: SendMessageFn;
+    waitUntil: (promise: Promise<unknown>) => void;
+  }) => void | Promise<void>;
+}
+
+export function isTaskDispatch<D extends object>(
+  dispatch: D
+): dispatch is Extract<D, TaskDispatch> {
+  return "task" in dispatch;
+}
+
+/**
+ * The task runs after the ack with the per-delivery send, so hosted
+ * admission can capture task-initiated sends; a startup-captured send
+ * bypasses capture.
+ */
+export function acknowledgeTask(
+  args: ChannelHandlerArgs,
+  kind: string,
+  dispatch: TaskDispatch,
+  extra: Record<string, unknown>
+): Response {
+  scheduleAfterAck(args, kind, () =>
+    dispatch.task({ send: args.send, waitUntil: args.waitUntil })
+  );
+  return tagOutcome(
+    Response.json(
+      { ok: true, dispatched: true, mode: "task", ...extra },
+      { status: 202 }
+    ),
+    "task"
+  );
+}
+
+const PROPAGATE_BACKGROUND_ERRORS = Symbol("propagateBackgroundErrors");
+
+type PropagatingHandlerArgs = ChannelHandlerArgs & {
+  [PROPAGATE_BACKGROUND_ERRORS]?: true;
+};
+
+/**
+ * Hosted admission opts in so a failed background task rejects `waitUntil`
+ * (a retryable 503 for the control plane) instead of being logged locally.
+ */
+export function withPropagatingBackgroundErrors(
+  args: ChannelHandlerArgs
+): ChannelHandlerArgs {
+  return Object.assign(args, { [PROPAGATE_BACKGROUND_ERRORS]: true as const });
+}
+
+/**
+ * Run `work` after the current turn so the 202 flushes first, inside the
+ * delivery's `waitUntil` window. Locally a failure is logged and swallowed;
+ * see {@link withPropagatingBackgroundErrors} for hosted admission.
+ */
+export function scheduleAfterAck(
+  args: ChannelHandlerArgs,
+  kind: string,
+  work: () => void | Promise<void>
+): void {
+  args.waitUntil(
+    new Promise<void>((resolve, reject) => {
+      setImmediate(() => {
+        Promise.resolve()
+          .then(work)
+          .then(
+            () => resolve(),
+            (error: unknown) => {
+              if (
+                (args as PropagatingHandlerArgs)[
+                  PROPAGATE_BACKGROUND_ERRORS
+                ] === true
+              ) {
+                reject(error);
+                return;
+              }
+              const detail =
+                error instanceof Error
+                  ? (error.stack ?? error.message)
+                  : String(error);
+              console.error(`[${kind}] background dispatch failed: ${detail}`);
+              resolve();
+            }
+          );
+      });
+    })
+  );
+}

package/src/internal/chat-client.ts

@@ -1,5 +1,5 @@
 /**
- * `agent-serve chat` — a minimal terminal client for a served agent. It
+ * `agent-sdk chat` — a minimal terminal client for a served agent. It
  * drives only the public HTTP API (create session, follow-up, NDJSON
  * stream), so it works against any agent-serve server and demonstrates the
  * same wire protocol the playground and curl use. Renders streamed

package/src/internal/cli-ax.ts

@@ -441,10 +441,6 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
   return loginExit;
 }
 
-/**
- * `chat` — talk to a running (or `--prod` hosted) agent. With `--json`,
- * prints a trajectory instead of the interactive UI.
- */
 /**
  * `resume [sessionId]` — reattach the interactive chat REPL to an existing
  * session. When the id is omitted, picks the most recently updated
@@ -481,6 +477,10 @@ function trimNonEmpty(value: string | undefined): string | undefined {
   return trimmed === "" ? undefined : trimmed;
 }
 
+/**
+ * `chat` — talk to a running (or `--prod` hosted) agent. With `--json`,
+ * prints a trajectory instead of the interactive UI.
+ */
 export async function cmdChat(options: AxCliOptions): Promise<number> {
   const message = options.messages?.[0];
   // chat never starts an ephemeral server — default to local serve URL.
@@ -704,7 +704,7 @@ export async function cmdRun(options: AxCliOptions): Promise<number> {
 }
 
 /**
- * `agent-serve call <tool>` — deterministic tool invocation over
+ * `agent-sdk call <tool>` — deterministic tool invocation over
  * `POST /v1/tools/:toolName` (ephemeral local server unless --url).
  */
 export async function cmdCall(options: AxCliOptions): Promise<number> {

package/src/internal/cli-bitbucket.ts

@@ -0,0 +1,477 @@
+/**
+ * `agent-sdk bitbucket …` — replay a pull request into a local
+ * `bitbucketChannel()` and list the discovered Bitbucket channels.
+ *
+ * Like GitLab, Bitbucket repository hooks POST to a public URL, so live
+ * forwarding needs a tunnel (`bitbucket forward` prints the recipe). Replay
+ * covers the local loop without one: it reads the PR over REST
+ * (`BITBUCKET_TOKEN`) in the host's dialect and POSTs Bitbucket-shaped
+ * payloads with `X-Hub-Signature` computed from `--secret` /
+ * `BITBUCKET_WEBHOOK_SECRET`.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve as resolvePath } from "node:path";
+import {
+  type BitbucketApiPullRequest,
+  bitbucketApiBaseUrl,
+  createBitbucketApi,
+  createBitbucketClient,
+} from "../channels/bitbucket/api.js";
+import {
+  type BitbucketChannelTarget,
+  findBitbucketChannelTargets,
+} from "../channels/bitbucket/bitbucket-channel.js";
+import { signBitbucketWebhookBody } from "../channels/bitbucket/bitbucket-webhook.js";
+import {
+  BITBUCKET_SYNTHESIZABLE_EVENTS,
+  parseBitbucketPrRef,
+  type SynthesizedBitbucketEvent,
+  selectBitbucketReplayEvents,
+  synthesizeBitbucketEvent,
+} from "../channels/bitbucket/replay.js";
+import { channelForwardUrl } from "../channels/github/forward.js";
+import { resolveAgentMounts } from "./discovery.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3000;
+
+export interface BitbucketCliOptions {
+  dir: string;
+  slug?: string;
+  channel?: string;
+  host?: string;
+  port?: number;
+  /** Explicit delivery URL (skips URL derivation). */
+  url?: string;
+  /** Comma/space-separated event keys (either dialect), or `*` for the declared set. */
+  events?: string;
+  /** Hook secret used to sign `X-Hub-Signature` (defaults to BITBUCKET_WEBHOOK_SECRET). */
+  secret?: string;
+  json?: boolean;
+  /** replay: PR URL (Cloud or Data Center) or `workspace/repo#N`. */
+  prUrl?: string;
+  /** replay: comment body. */
+  comment?: string;
+  dryRun?: boolean;
+  out?: string;
+}
+
+const BITBUCKET_HELP = `${CLI} bitbucket — replay Bitbucket pull-request webhooks into a local agent
+
+Usage:
+  ${CLI} bitbucket replay   <pr_url|workspace/repo#N> [--events a,b,c | *]
+                                 [--comment "…"] [--dir .] [--slug S] [--channel C]
+                                 [--host H] [--port N] [--url URL] [--secret S]
+                                 [--dry-run] [--out DIR] [--json]
+  ${CLI} bitbucket events   [--dir .] [--host H] [--port N] [--json]
+  ${CLI} bitbucket forward  [--dir .] [--host H] [--port N]
+
+Commands:
+  replay    Synthesize webhook payloads from a pull request you can *read* and
+            POST them to the discovered bitbucketChannel()s. Reads the PR over
+            the REST API with BITBUCKET_TOKEN in the host's dialect (Cloud 2.0
+            for bitbucket.org, Data Center 1.0 for a /projects/…/repos/… URL),
+            builds payloads in that dialect for --events (default
+            pullrequest:created; \`*\` = the channel's declared events; Data
+            Center keys such as pr:opened are accepted:
+            ${BITBUCKET_SYNTHESIZABLE_EVENTS.join(", ")}),
+            and signs X-Hub-Signature from --secret / BITBUCKET_WEBHOOK_SECRET.
+            --dry-run prints them; --out writes them as fixtures.
+  events    List discovered Bitbucket channels and the event keys each accepts.
+  forward   Print the repository-hook + tunnel recipe for live deliveries.
+
+Prerequisites:
+  - BITBUCKET_TOKEN with pull request read access (Data Center: an HTTP
+    access token; or set BITBUCKET_API_BASE_URL to the REST base).
+  - The agent already serving (\`${CLI} serve --dir . --dev\`).
+`;
+
+export async function cmdBitbucket(
+  subcommand: string | undefined,
+  options: BitbucketCliOptions
+): Promise<number> {
+  switch (subcommand) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(BITBUCKET_HELP);
+      return subcommand === undefined ? 1 : 0;
+    case "replay":
+      return cmdBitbucketReplay(options);
+    case "events":
+      return cmdBitbucketEvents(options);
+    case "forward":
+      return cmdBitbucketForward(options);
+    default:
+      process.stderr.write(`Unknown bitbucket subcommand: ${subcommand}\n`);
+      process.stdout.write(BITBUCKET_HELP);
+      return 1;
+  }
+}
+
+interface ReplayTarget {
+  slug: string;
+  channelId: string;
+  url: string;
+  events: string[];
+}
+
+async function resolveTargets(
+  options: BitbucketCliOptions
+): Promise<ReplayTarget[] | undefined> {
+  const dir = resolvePath(options.dir);
+  const channels = findBitbucketChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  let candidates: BitbucketChannelTarget[] = channels;
+  if (options.slug !== undefined) {
+    candidates = candidates.filter((c) => c.slug === options.slug);
+  }
+  if (options.channel !== undefined) {
+    candidates = candidates.filter((c) => c.channelId === options.channel);
+  }
+  if (options.url !== undefined && candidates.length > 1) {
+    process.stderr.write(
+      "--url targets a single channel; narrow with --slug/--channel\n"
+    );
+    return undefined;
+  }
+  if (candidates.length === 0 && options.url === undefined) {
+    process.stderr.write(
+      "no Bitbucket channel found. Author agent/channels/bitbucket.ts with bitbucketChannel(), or pass --url.\n"
+    );
+    return undefined;
+  }
+  if (options.url !== undefined) {
+    return [
+      {
+        slug: candidates[0]?.slug ?? "",
+        channelId: candidates[0]?.channelId ?? "",
+        url: options.url,
+        events: candidates[0]?.events ?? [],
+      },
+    ];
+  }
+  return candidates.map((c) => ({
+    slug: c.slug,
+    channelId: c.channelId,
+    url: channelForwardUrl({
+      host,
+      port,
+      slug: c.slug,
+      channelId: c.channelId,
+      routePath: c.routePath,
+    }),
+    events: c.events,
+  }));
+}
+
+async function cmdBitbucketReplay(
+  options: BitbucketCliOptions
+): Promise<number> {
+  const prUrl = options.prUrl;
+  if (prUrl === undefined || prUrl === "") {
+    process.stderr.write(
+      "bitbucket replay needs a PR URL or workspace/repo#N\n"
+    );
+    return 1;
+  }
+  const ref = parseBitbucketPrRef(prUrl);
+  if (ref === undefined) {
+    process.stderr.write(`could not parse pull request ref: ${prUrl}\n`);
+    return 1;
+  }
+  const targets = await resolveTargets(options);
+  if (targets === undefined) {
+    return 1;
+  }
+
+  const requested = parseEventList(options.events);
+  const declared = [...new Set(targets.flatMap((target) => target.events))];
+  const { events, unsupported } = selectBitbucketReplayEvents(
+    requested,
+    declared
+  );
+  if (unsupported.length > 0) {
+    process.stderr.write(
+      `[agent-sdk] cannot synthesize (skipped): ${unsupported.join(", ")}\n`
+    );
+  }
+  if (events.length === 0) {
+    process.stderr.write("no synthesizable events selected\n");
+    return 1;
+  }
+
+  // Read the PR in the host's dialect — read access is enough.
+  const apiBaseUrl = bitbucketApiBaseUrl({
+    dialect: ref.dialect,
+    repoHtmlUrl: ref.repository.htmlUrl,
+  });
+  let pullRequest: BitbucketApiPullRequest;
+  try {
+    const client = createBitbucketClient({ apiBaseUrl });
+    pullRequest = await createBitbucketApi(
+      client,
+      ref.repository
+    ).getPullRequest(ref.id);
+  } catch (error) {
+    process.stderr.write(
+      `failed to read ${ref.label} via ${apiBaseUrl ?? "(no API base)"}: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+
+  const synthesized: SynthesizedBitbucketEvent[] = [];
+  for (const event of events) {
+    const result = synthesizeBitbucketEvent({
+      event,
+      ref,
+      pullRequest,
+      comment: options.comment,
+    });
+    if ("error" in result) {
+      process.stderr.write(`[agent-sdk] skipping ${event}: ${result.error}\n`);
+      continue;
+    }
+    synthesized.push(result);
+  }
+  if (synthesized.length === 0) {
+    process.stderr.write("nothing to replay after synthesis\n");
+    return 1;
+  }
+
+  const secret = options.secret ?? process.env.BITBUCKET_WEBHOOK_SECRET;
+  process.stderr.write(
+    `[agent-sdk] replaying ${ref.label} (${ref.dialect}; ${synthesized
+      .map((event) => event.eventType)
+      .join(
+        ", "
+      )}) → ${targets.length} channel${targets.length === 1 ? "" : "s"}\n`
+  );
+
+  const report: Array<Record<string, unknown>> = [];
+  let anyRejected = false;
+  for (const event of synthesized) {
+    const body = JSON.stringify(event.payload);
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      "x-event-key": event.header,
+      "x-request-uuid": randomUUID(),
+    };
+    if (secret !== undefined && secret !== "") {
+      headers["x-hub-signature"] = signBitbucketWebhookBody(body, secret);
+    }
+    if (options.out !== undefined) {
+      const file = await writeReplayFixture(options.out, event);
+      process.stderr.write(`[agent-sdk] wrote ${file}\n`);
+    }
+    if (options.dryRun === true) {
+      report.push({ ...eventReport(event), payload: event.payload });
+      if (options.json !== true) {
+        process.stdout.write(
+          `--- ${event.header} ---\n${JSON.stringify(event.payload, null, 2)}\n`
+        );
+      }
+      continue;
+    }
+    const deliveries = await deliverReplayEvent(
+      body,
+      headers,
+      event.eventType,
+      targets
+    );
+    if (deliveries.length === 0 || deliveries.some((d) => !d.ok)) {
+      anyRejected = true;
+    }
+    report.push({ ...eventReport(event), deliveries });
+    if (options.json !== true) {
+      const summary =
+        deliveries
+          .map(
+            (d) => `${d.label} ${d.status || "ERR"}${d.ok ? "" : " (rejected)"}`
+          )
+          .join(", ") || "(no matching channel)";
+      process.stderr.write(`[agent-sdk]   ${event.header} → ${summary}\n`);
+    }
+  }
+
+  if (options.json === true) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          pr: ref.label,
+          dialect: ref.dialect,
+          dryRun: options.dryRun === true,
+          events: report,
+        },
+        null,
+        2
+      )}\n`
+    );
+  }
+  return anyRejected ? 1 : 0;
+}
+
+interface ReplayDelivery {
+  label: string;
+  status: number;
+  ok: boolean;
+  error?: string;
+}
+
+async function deliverReplayEvent(
+  body: string,
+  headers: Record<string, string>,
+  eventType: string,
+  targets: readonly ReplayTarget[]
+): Promise<ReplayDelivery[]> {
+  const recipients = targets.filter(
+    (target) => target.events.length === 0 || target.events.includes(eventType)
+  );
+  return Promise.all(
+    recipients.map(async (target) => {
+      const label =
+        target.slug === ""
+          ? target.channelId
+          : `${target.slug}/${target.channelId}`;
+      try {
+        const response = await fetch(target.url, {
+          method: "POST",
+          headers,
+          body,
+        });
+        await response.text().catch(() => undefined);
+        return { label, status: response.status, ok: response.ok };
+      } catch (error) {
+        return {
+          label,
+          status: 0,
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })
+  );
+}
+
+function eventReport(
+  event: SynthesizedBitbucketEvent
+): Record<string, unknown> {
+  return { event: event.eventType, header: event.header };
+}
+
+async function writeReplayFixture(
+  outDir: string,
+  event: SynthesizedBitbucketEvent
+): Promise<string> {
+  const dir = resolvePath(outDir);
+  await mkdir(dir, { recursive: true });
+  const file = join(
+    dir,
+    `bitbucket-${event.header.replace(/[^\w.-]+/g, "-")}.json`
+  );
+  await writeFile(file, `${JSON.stringify(event.payload, null, 2)}\n`);
+  return file;
+}
+
+async function cmdBitbucketEvents(
+  options: BitbucketCliOptions
+): Promise<number> {
+  const dir = resolvePath(options.dir);
+  const channels = findBitbucketChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  const rows = channels.map((c) => ({
+    slug: c.slug,
+    channelId: c.channelId,
+    url: channelForwardUrl({
+      host,
+      port,
+      slug: c.slug,
+      channelId: c.channelId,
+      routePath: c.routePath,
+    }),
+    events: c.events,
+  }));
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify({ channels: rows }, null, 2)}\n`);
+    return 0;
+  }
+  if (rows.length === 0) {
+    process.stdout.write("no Bitbucket channels found\n");
+    return 0;
+  }
+  for (const row of rows) {
+    const label =
+      row.slug === "" ? row.channelId : `${row.slug}/${row.channelId}`;
+    process.stdout.write(
+      `${label}\n  ${row.url}\n  ${row.events.join(", ")}\n`
+    );
+  }
+  return 0;
+}
+
+async function cmdBitbucketForward(
+  options: BitbucketCliOptions
+): Promise<number> {
+  const dir = resolvePath(options.dir);
+  const channels = findBitbucketChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  if (channels.length === 0) {
+    process.stderr.write(
+      "no Bitbucket channel found. Author agent/channels/bitbucket.ts with bitbucketChannel().\n"
+    );
+    return 1;
+  }
+  const lines = [
+    "Bitbucket repository hooks deliver to a public URL; there is no local relay.",
+    "To receive live deliveries:",
+    "",
+    `  1. Expose the agent: e.g. \`cloudflared tunnel --url http://${host}:${port}\``,
+    "     (or ngrok / any HTTPS tunnel) and note the public base URL.",
+    "  2. In Bitbucket → Repository settings → Webhooks, add one hook per channel",
+    "     (Cloud triggers use the keys below; Data Center shows the pr:* names):",
+  ];
+  for (const c of channels) {
+    const path = channelForwardUrl({
+      host,
+      port,
+      slug: c.slug,
+      channelId: c.channelId,
+      routePath: c.routePath,
+    }).replace(`http://${host}:${port}`, "<tunnel>");
+    lines.push(`       URL:      ${path}`);
+    lines.push(`       Triggers: ${c.events.join(", ")}`);
+    lines.push(
+      "       Secret:   the value of BITBUCKET_WEBHOOK_SECRET (or webhookSecret)"
+    );
+  }
+  lines.push(
+    "",
+    "  3. Serve with the secret set so X-Hub-Signature is verified:",
+    `     BITBUCKET_WEBHOOK_SECRET=… ${CLI} serve --dir . --dev`,
+    "",
+    `Without a tunnel, \`${CLI} bitbucket replay <pr_url>\` exercises the same channel locally.`,
+    ""
+  );
+  process.stdout.write(lines.join("\n"));
+  return 0;
+}
+
+function parseEventList(value: string | undefined): string[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const events = value
+    .split(/[\s,]+/)
+    .map((event) => event.trim())
+    .filter(Boolean);
+  return events.length === 0 ? undefined : events;
+}

package/src/internal/cli-convert-automation.ts

@@ -1,5 +1,5 @@
 /**
- * `agent-serve convert-automation <url>` — export a Cursor Automation into
+ * `agent-sdk convert-automation <url>` — export a Cursor Automation into
  * an agentsdk project.
  *
  * Fetches the automation's workflow from the backend export endpoint
@@ -17,13 +17,13 @@
 
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import {
-  type ConvertedMcpConnection,
-  type ConvertWorkflowResult,
-  convertWorkflow,
-  type WorkflowJson,
-} from "./convert-automation/index.js";
+import { convertWorkflow } from "./convert-automation/convert-workflow.js";
 import { slugify } from "./convert-automation/slug.js";
+import type {
+  ConvertedMcpConnection,
+  ConvertWorkflowResult,
+  WorkflowJson,
+} from "./convert-automation/types.js";
 import {
   cursorExternalApiUrl,
   resolveApiKey,