@cursor/july 0.1.1

package/src/internal/event-mapper.ts

@@ -0,0 +1,272 @@
+/**
+ * Maps the Cursor harness's streaming delta vocabulary
+ * (`InteractionUpdate`) onto the framework's channel event vocabulary
+ * (`SessionEvent` payloads). One mapper instance covers one turn.
+ */
+
+import type { InteractionUpdate, ToolCall } from "@cursor/sdk";
+import type { SessionEventPayload, TurnUsage } from "../types.js";
+
+const CUSTOM_TOOLS_PROVIDER = "custom-user-tools";
+
+export interface ToolCallDescription {
+  toolName: string;
+  args?: unknown;
+  subagent?: { name?: string; description?: string };
+}
+
+export interface ToolResultDescription {
+  output?: unknown;
+  isError: boolean;
+}
+
+export class TurnEventMapper {
+  private textAccumulator = "";
+  private reasoningAccumulator = "";
+  private usageTotal: TurnUsage | undefined;
+  private lastAssistantText: string | undefined;
+  private summaryTitle: string | undefined;
+
+  constructor(private readonly emit: (payload: SessionEventPayload) => void) {}
+
+  /** Per-turn token usage summed across model steps. */
+  get usage(): TurnUsage | undefined {
+    return this.usageTotal;
+  }
+
+  /** The final assistant text block of the turn, when one was produced. */
+  get finalText(): string | undefined {
+    return this.lastAssistantText;
+  }
+
+  /** Conversation summary produced by the harness (used as session title). */
+  get title(): string | undefined {
+    return this.summaryTitle;
+  }
+
+  handleUpdate(update: InteractionUpdate): void {
+    switch (update.type) {
+      case "text-delta": {
+        this.textAccumulator += update.text;
+        this.emit({
+          type: "message.appended",
+          data: { delta: update.text, text: this.textAccumulator },
+        });
+        return;
+      }
+      case "thinking-delta": {
+        this.reasoningAccumulator += update.text;
+        this.emit({
+          type: "reasoning.appended",
+          data: { delta: update.text, text: this.reasoningAccumulator },
+        });
+        return;
+      }
+      case "thinking-completed": {
+        if (this.reasoningAccumulator !== "") {
+          this.reasoningAccumulator = "";
+        }
+        this.emit({
+          type: "reasoning.completed",
+          data: { durationMs: update.thinkingDurationMs },
+        });
+        return;
+      }
+      case "tool-call-started": {
+        this.flushAssistantText("tool_call");
+        const description = describeToolCall(update.toolCall);
+        this.emit({
+          type: "actions.requested",
+          data: {
+            calls: [
+              {
+                callId: update.callId,
+                toolName: description.toolName,
+                args: description.args,
+              },
+            ],
+          },
+        });
+        if (description.subagent !== undefined) {
+          this.emit({
+            type: "subagent.called",
+            data: {
+              callId: update.callId,
+              name: description.subagent.name,
+              description: description.subagent.description,
+            },
+          });
+        }
+        return;
+      }
+      case "tool-call-completed": {
+        const description = describeToolCall(update.toolCall);
+        const result = describeToolResult(update.toolCall);
+        this.emit({
+          type: "action.result",
+          data: {
+            callId: update.callId,
+            toolName: description.toolName,
+            output: result.output,
+            isError: result.isError,
+          },
+        });
+        if (description.subagent !== undefined) {
+          this.emit({
+            type: "subagent.completed",
+            data: { callId: update.callId, name: description.subagent.name },
+          });
+        }
+        return;
+      }
+      case "step-started": {
+        this.emit({ type: "step.started", data: { stepId: update.stepId } });
+        return;
+      }
+      case "step-completed": {
+        this.emit({
+          type: "step.completed",
+          data: { stepId: update.stepId, durationMs: update.stepDurationMs },
+        });
+        return;
+      }
+      case "turn-ended": {
+        if (update.usage !== undefined) {
+          this.usageTotal = addUsage(this.usageTotal, update.usage);
+        }
+        return;
+      }
+      case "summary": {
+        this.summaryTitle = update.summary;
+        return;
+      }
+      case "user-message-appended":
+      case "partial-tool-call":
+      case "token-delta":
+      case "summary-started":
+      case "summary-completed":
+      case "shell-output-delta":
+        return;
+      default: {
+        // Future harness update types are ignored rather than fatal.
+        return;
+      }
+    }
+  }
+
+  /** Close out the turn: finalize any open assistant text block. */
+  finish(): void {
+    this.flushAssistantText("stop");
+  }
+
+  private flushAssistantText(finishReason: "stop" | "tool_call"): void {
+    if (this.textAccumulator === "") {
+      return;
+    }
+    const text = this.textAccumulator;
+    this.textAccumulator = "";
+    this.lastAssistantText = text;
+    this.emit({
+      type: "message.completed",
+      data: { text, finishReason },
+    });
+  }
+}
+
+/**
+ * Human-meaningful tool identity for stream events. In-process tools calls
+ * arrive as MCP calls against the synthetic `custom-user-tools` server; they
+ * surface under the customer's bare tool name.
+ */
+export function describeToolCall(toolCall: ToolCall): ToolCallDescription {
+  switch (toolCall.type) {
+    case "mcp": {
+      const providerIdentifier = toolCall.args.providerIdentifier;
+      const toolName = toolCall.args.toolName;
+      if (providerIdentifier === CUSTOM_TOOLS_PROVIDER) {
+        return {
+          toolName: toolName ?? "custom-tool",
+          args: toolCall.args.args,
+        };
+      }
+      const bareName = toolName ?? "tool";
+      return {
+        toolName:
+          providerIdentifier === undefined || providerIdentifier === ""
+            ? bareName
+            : `${providerIdentifier}:${bareName}`,
+        args: toolCall.args.args,
+      };
+    }
+    case "task": {
+      const subagentType = toolCall.args.subagentType;
+      const subagentName = subagentType?.name ?? subagentType?.kind;
+      return {
+        toolName: "task",
+        args: {
+          description: toolCall.args.description,
+          ...(subagentName === undefined ? {} : { subagentType: subagentName }),
+        },
+        subagent: {
+          ...(subagentName === undefined ? {} : { name: subagentName }),
+          description: toolCall.args.description,
+        },
+      };
+    }
+    default: {
+      return {
+        toolName: toolCall.type,
+        args: (toolCall as { args?: unknown }).args,
+      };
+    }
+  }
+}
+
+export function describeToolResult(toolCall: ToolCall): ToolResultDescription {
+  const result = (toolCall as { result?: unknown }).result as
+    | { status: "success"; value: unknown }
+    | { status: "error"; error: unknown }
+    | undefined;
+  if (result === undefined || result === null) {
+    return { isError: false };
+  }
+  if (result.status === "error") {
+    return { output: result.error, isError: true };
+  }
+
+  if (toolCall.type === "mcp") {
+    const value = result.value as {
+      content?: Array<{ text?: { text: string } }>;
+      isError?: boolean;
+    };
+    const text = (value.content ?? [])
+      .map((item) => item.text?.text ?? "")
+      .filter((part) => part !== "")
+      .join("\n");
+    return {
+      output: text === "" ? value : text,
+      isError: value.isError === true,
+    };
+  }
+
+  return { output: result.value, isError: false };
+}
+
+function addUsage(total: TurnUsage | undefined, usage: TurnUsage): TurnUsage {
+  if (total === undefined) {
+    return { ...usage };
+  }
+  return {
+    inputTokens: total.inputTokens + usage.inputTokens,
+    outputTokens: total.outputTokens + usage.outputTokens,
+    cacheReadTokens: total.cacheReadTokens + usage.cacheReadTokens,
+    cacheWriteTokens: total.cacheWriteTokens + usage.cacheWriteTokens,
+    ...(total.reasoningTokens !== undefined ||
+    usage.reasoningTokens !== undefined
+      ? {
+          reasoningTokens:
+            (total.reasoningTokens ?? 0) + (usage.reasoningTokens ?? 0),
+        }
+      : {}),
+  };
+}

package/src/internal/frontmatter.ts

@@ -0,0 +1,77 @@
+/**
+ * Minimal frontmatter parser. Supports the flat `key: value` scalar subset
+ * used by authored markdown (skill descriptions, schedule cron expressions)
+ * without pulling in a YAML dependency.
+ */
+
+export interface ParsedFrontmatter {
+  data: Record<string, string>;
+  body: string;
+}
+
+const FRONTMATTER_OPEN = /^---\s*$/;
+
+export function parseFrontmatter(source: string): ParsedFrontmatter {
+  const lines = source.split(/\r?\n/);
+  if (lines.length === 0 || !FRONTMATTER_OPEN.test(lines[0] ?? "")) {
+    return { data: {}, body: source };
+  }
+
+  let closeIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (FRONTMATTER_OPEN.test(lines[i] ?? "")) {
+      closeIndex = i;
+      break;
+    }
+  }
+  if (closeIndex === -1) {
+    return { data: {}, body: source };
+  }
+
+  const data: Record<string, string> = {};
+  for (const line of lines.slice(1, closeIndex)) {
+    if (line.trim() === "" || line.trim().startsWith("#")) {
+      continue;
+    }
+    const separator = line.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+    const key = line.slice(0, separator).trim();
+    if (key === "") {
+      continue;
+    }
+    data[key] = unquote(line.slice(separator + 1).trim());
+  }
+
+  const body = lines
+    .slice(closeIndex + 1)
+    .join("\n")
+    .replace(/^\n+/, "");
+  return { data, body };
+}
+
+export function serializeFrontmatter(data: Record<string, string>): string {
+  const lines = Object.entries(data).map(
+    ([key, value]) => `${key}: ${quoteIfNeeded(value)}`
+  );
+  return `---\n${lines.join("\n")}\n---\n`;
+}
+
+function unquote(value: string): string {
+  if (
+    value.length >= 2 &&
+    ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'")))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function quoteIfNeeded(value: string): string {
+  if (/[:#'"\n]/.test(value)) {
+    return JSON.stringify(value);
+  }
+  return value;
+}

package/src/internal/github-fanout.ts

@@ -0,0 +1,159 @@
+/**
+ * Local fan-out proxy for `agent-serve github forward`.
+ *
+ * `gh webhook forward` can only target a single URL, and GitHub allows just one
+ * forwarder per repo/org. To feed several GitHub channels at once, we run one
+ * forwarder into this loopback proxy, which re-posts each delivery — raw body
+ * and signature headers intact, so per-channel `X-Hub-Signature-256` checks
+ * still pass — to every channel whose declared event set matches the
+ * delivery's `x-github-event`.
+ */
+
+import {
+  createServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+import {
+  type GitHubForwardTarget,
+  targetLabel,
+} from "../channels/github/forward.js";
+
+/** Request headers copied verbatim from gh onto each fanned-out delivery. */
+export const FANOUT_FORWARD_HEADERS: readonly string[] = [
+  "content-type",
+  "x-github-event",
+  "x-github-delivery",
+  "x-github-hook-id",
+  "x-hub-signature",
+  "x-hub-signature-256",
+  "user-agent",
+  "accept",
+];
+
+export interface FanoutServer {
+  /** Loopback URL to point `gh webhook forward --url` at. */
+  url: string;
+  close(): void;
+}
+
+export interface FanoutOptions {
+  /** Sink for per-delivery failures. Defaults to `process.stderr`. */
+  logger?: (line: string) => void;
+}
+
+/** Start a loopback proxy that fans deliveries out to {@link targets}. */
+export async function startFanoutServer(
+  targets: readonly GitHubForwardTarget[],
+  options: FanoutOptions = {}
+): Promise<FanoutServer> {
+  const server = createServer((req, res) => {
+    handleFanoutRequest(req, res, targets, options);
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      resolve();
+    });
+  });
+  const address = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    close: () => {
+      server.close();
+    },
+  };
+}
+
+function handleFanoutRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  targets: readonly GitHubForwardTarget[],
+  options: FanoutOptions
+): void {
+  const chunks: Buffer[] = [];
+  req.on("data", (chunk: Buffer) => {
+    chunks.push(chunk);
+  });
+  req.on("end", () => {
+    void fanoutDelivery(Buffer.concat(chunks), req.headers, targets, options)
+      .then((delivered) => {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ ok: true, delivered }));
+      })
+      .catch((error: unknown) => {
+        res.writeHead(502, { "content-type": "application/json" });
+        res.end(
+          JSON.stringify({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        );
+      });
+  });
+}
+
+/**
+ * Re-post a single delivery to the matching targets, returning the labels that
+ * accepted it. Only targets whose event set includes the delivery's
+ * `x-github-event` receive it (all of them when the header is absent).
+ */
+export async function fanoutDelivery(
+  body: Buffer,
+  headers: IncomingMessage["headers"],
+  targets: readonly GitHubForwardTarget[],
+  options: FanoutOptions = {}
+): Promise<string[]> {
+  const log = options.logger ?? ((line) => process.stderr.write(line));
+  const event =
+    typeof headers["x-github-event"] === "string"
+      ? headers["x-github-event"]
+      : undefined;
+  const outbound: Record<string, string> = {};
+  for (const name of FANOUT_FORWARD_HEADERS) {
+    const value = headers[name];
+    if (typeof value === "string") {
+      outbound[name] = value;
+    }
+  }
+  const recipients = targets.filter(
+    (target) => event === undefined || target.events.includes(event)
+  );
+  // Reuse one Uint8Array view across recipients (Buffer isn't a BodyInit).
+  const payload = new Uint8Array(body);
+  const delivered: string[] = [];
+  // Bounded by the number of GitHub channels in the project (a handful), so
+  // unbounded-concurrency concerns do not apply here.
+  await Promise.all(
+    recipients.map(async (target) => {
+      const label = targetLabel(target);
+      try {
+        const response = await fetch(target.url, {
+          method: "POST",
+          headers: outbound,
+          body: payload,
+        });
+        if (!response.ok) {
+          log(
+            `[agent-serve] delivery to ${label} failed: HTTP ${response.status}\n`
+          );
+          return;
+        }
+        delivered.push(label);
+      } catch (error) {
+        log(
+          `[agent-serve] delivery to ${label} failed: ${
+            error instanceof Error ? error.message : String(error)
+          }\n`
+        );
+      }
+    })
+  );
+  if (recipients.length > 0 && delivered.length === 0) {
+    throw new Error(
+      `fan-out delivery failed for all ${recipients.length} matching channel(s)`
+    );
+  }
+  return delivered;
+}

package/src/internal/handleAgentServeTrigger.ts

@@ -0,0 +1,156 @@
+/**
+ * Unified entry for dispatching agent-serve triggers from an external ingress
+ * (e.g. the Cursor backend GitHub webhook). Mirrors Automations'
+ * `handleAutomationTrigger`, but only GitHub is supported for now.
+ *
+ * Callers must authenticate the delivery before invoking this (the backend
+ * verifies GitHub HMAC at `/github_webhook`). This fan-out does not re-check
+ * signatures — same trust model as Bugbot after `verifyGithubRequest`.
+ *
+ * Each agent's `onPullRequest` / `onComment` / … hooks decide whether to run.
+ */
+
+import {
+  dispatchGitHubWebhook,
+  getGitHubChannelOptions,
+} from "../channels/github/github-channel.js";
+import type { GitHubChannelOptions } from "../channels/github/types.js";
+import type { ChannelHandlerArgs } from "../types.js";
+
+export interface AgentServeGitHubTriggerTarget {
+  /** Agent mount slug (empty string in single-agent mode). */
+  slug: string;
+  /** Options from the agent's `githubChannel({ ... })` definition. */
+  options: GitHubChannelOptions;
+  /** Per-agent channel handler args (`send`, `waitUntil`, `host`, …). */
+  args: ChannelHandlerArgs;
+}
+
+export interface AgentServeGitHubTriggerEvent {
+  type: "github";
+  /** Raw webhook body (signature already verified by the caller). */
+  bodyText: string;
+  eventName: string | null;
+  deliveryId?: string;
+  targets: AgentServeGitHubTriggerTarget[];
+}
+
+export type AgentServeTriggerEvent = AgentServeGitHubTriggerEvent;
+
+export interface AgentServeTriggerTargetResult {
+  slug: string;
+  status: number;
+  body: unknown;
+}
+
+export interface AgentServeTriggerResult {
+  ok: boolean;
+  event: string | null;
+  targets: AgentServeTriggerTargetResult[];
+}
+
+/**
+ * Build fan-out targets from mounted agent projects that export a github
+ * channel created via {@link githubChannel}.
+ */
+export function collectGitHubTriggerTargets(input: {
+  mounts: Array<{
+    slug: string;
+    channels: Array<{ id: string; definition: object }>;
+    buildHandlerArgs: (channelId: string) => ChannelHandlerArgs;
+  }>;
+}): AgentServeGitHubTriggerTarget[] {
+  const targets: AgentServeGitHubTriggerTarget[] = [];
+  for (const mount of input.mounts) {
+    const github = mount.channels.find((channel) => channel.id === "github");
+    if (github === undefined) {
+      continue;
+    }
+    const options = getGitHubChannelOptions(github.definition);
+    if (options === undefined) {
+      continue;
+    }
+    targets.push({
+      slug: mount.slug,
+      options,
+      args: mount.buildHandlerArgs("github"),
+    });
+  }
+  return targets;
+}
+
+/**
+ * Dispatch an agent-serve trigger. GitHub only for now.
+ */
+export async function handleAgentServeTrigger(
+  event: AgentServeTriggerEvent
+): Promise<AgentServeTriggerResult> {
+  switch (event.type) {
+    // TODO: Add support for other event types (e.g. Linear, Slack, etc.).
+    case "github":
+      return handleAgentServeGitHubTrigger(event);
+    default: {
+      const _: never = event.type;
+      throw new Error(
+        `handleAgentServeTrigger: unknown event type: ${String(_)}`
+      );
+    }
+  }
+}
+
+async function handleAgentServeGitHubTrigger(
+  event: AgentServeGitHubTriggerEvent
+): Promise<AgentServeTriggerResult> {
+  if (event.eventName === "ping") {
+    return {
+      ok: true,
+      event: "ping",
+      targets: [],
+    };
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(event.bodyText) as unknown;
+  } catch {
+    return {
+      ok: false,
+      event: event.eventName,
+      targets: [
+        {
+          slug: "",
+          status: 400,
+          body: { ok: false, error: "invalid_json" },
+        },
+      ],
+    };
+  }
+
+  const targets: AgentServeTriggerTargetResult[] = [];
+  for (const target of event.targets) {
+    const response = await dispatchGitHubWebhook({
+      options: target.options,
+      eventName: event.eventName,
+      payload,
+      deliveryId: event.deliveryId,
+      args: target.args,
+    });
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch {
+      body = { ok: false, error: "invalid_response_json" };
+    }
+    targets.push({
+      slug: target.slug,
+      status: response.status,
+      body,
+    });
+  }
+
+  return {
+    ok: true,
+    event: event.eventName,
+    targets,
+  };
+}