@cursor/bdk 0.2.1 → 0.2.3

package/src/extensions/cursor-grokbot-agents/lib/backend.ts

@@ -0,0 +1,208 @@
+/**
+ * The `/v0/grokbot` session API as the tools use it: the same four routes
+ * the grokbot runtime drives, on the external API host (`api.cursor.com`;
+ * they 404 on api2), under the host's Cursor API key. A session is a hosted
+ * Grok Bot agent of the key's account, get-or-created by name; messages go
+ * into its one conversation, and the transcript is read back as entries
+ * after a cursor, with the turn's status alongside.
+ */
+
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+  SIGN_IN_HINT,
+} from "../../../internal/cursor/credentials.js";
+import extension from "../extension.js";
+
+const REQUEST_TIMEOUT_MS = 60_000;
+
+export class GrokBotApiError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "GrokBotApiError";
+  }
+}
+
+// Type aliases, not interfaces: these flow into tool results.
+export type GrokBotSession = {
+  /** The hosted agent's durable id; every other route addresses it. */
+  sessionId: string;
+  /** The name as the backend stores it (trimmed). */
+  name: string;
+  createdAtMs: number;
+  /** Transcript tail: reading after it skips the conversation's history. */
+  latestUpdatedSeq: string;
+};
+
+export type GrokBotEntry = {
+  seq: string;
+  updatedSeq: string;
+  kind: string;
+  role?: string;
+  text?: string;
+  createdAtMs: number;
+};
+
+export type GrokBotTurnStatus = {
+  idle: boolean;
+  inFlight: boolean;
+  queued: number;
+};
+
+export type GrokBotEntriesPage = {
+  entries: GrokBotEntry[];
+  latestUpdatedSeq: string;
+  turn: GrokBotTurnStatus;
+};
+
+const sessionSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAtMs: z.number(),
+  latestUpdatedSeq: z.string(),
+});
+
+const sendSchema = z.object({
+  messageId: z.string(),
+  delivery: z.string(),
+});
+
+const entriesSchema: z.ZodType<GrokBotEntriesPage> = z.object({
+  entries: z.array(
+    z.object({
+      seq: z.string(),
+      updatedSeq: z.string(),
+      kind: z.string(),
+      role: z.string().optional(),
+      text: z.string().optional(),
+      createdAtMs: z.number(),
+    }),
+  ),
+  latestUpdatedSeq: z.string(),
+  turn: z.object({
+    idle: z.boolean(),
+    inFlight: z.boolean(),
+    queued: z.number(),
+  }),
+});
+
+export class GrokBotAgentsBackend {
+  constructor(
+    private readonly apiKey: () => string,
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  /** `POST /v0/grokbot/sessions`: the account's agent of that name, created when missing. */
+  async session(name: string): Promise<GrokBotSession> {
+    // No `instructions`: the agent is somebody's, configured in the app, and
+    // an omitted field never touches its stored profile.
+    const parsed = sessionSchema.parse(
+      await this.request("POST", "/v0/grokbot/sessions", { name }),
+    );
+    return {
+      sessionId: parsed.id,
+      name: parsed.name,
+      createdAtMs: parsed.createdAtMs,
+      latestUpdatedSeq: parsed.latestUpdatedSeq,
+    };
+  }
+
+  /** Deliver one user message to the agent's conversation. */
+  async send(sessionId: string, text: string): Promise<void> {
+    const { delivery } = sendSchema.parse(
+      await this.request("POST", `/v0/grokbot/sessions/${sessionId}/messages`, {
+        text,
+        messageId: randomUUID(),
+      }),
+    );
+    if (delivery !== "accepted_temporal" && delivery !== "duplicate") {
+      throw new GrokBotApiError(
+        `The Grok Bot agent's harness did not accept the message (delivery: ${delivery}).`,
+      );
+    }
+  }
+
+  /** Transcript entries after `afterUpdatedSeq`, oldest first, with the turn's status. */
+  async entries(sessionId: string, afterUpdatedSeq: string): Promise<GrokBotEntriesPage> {
+    return entriesSchema.parse(
+      await this.request(
+        "GET",
+        `/v0/grokbot/sessions/${sessionId}/entries?afterUpdatedSeq=${encodeURIComponent(afterUpdatedSeq)}`,
+      ),
+    );
+  }
+
+  async interrupt(sessionId: string, reason: string): Promise<void> {
+    await this.request("POST", `/v0/grokbot/sessions/${sessionId}/interrupt`, {
+      reason,
+    });
+  }
+
+  private async request(method: "GET" | "POST", path: string, body?: unknown): Promise<unknown> {
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${this.apiKey()}`,
+      "x-cursor-client-type": "agent-serve",
+      "x-request-id": randomUUID(),
+    };
+    if (body !== undefined) {
+      headers["content-type"] = "application/json";
+    }
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${cursorExternalApiUrl()}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch (error) {
+      throw new GrokBotApiError(
+        `Grok Bot API ${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new GrokBotApiError(
+        `Grok Bot API ${method} ${path} failed (${response.status}): ${apiErrorMessage(text)}`,
+        response.status,
+      );
+    }
+    return JSON.parse(text) as unknown;
+  }
+}
+
+let backend: GrokBotAgentsBackend | undefined;
+
+/** The process-wide backend for this mount, built on first use. */
+export function grokBotAgentsBackend(): GrokBotAgentsBackend {
+  backend ??= new GrokBotAgentsBackend(apiKey);
+  return backend;
+}
+
+export function apiKey(): string {
+  // Read per call: the host can sign in after the mount.
+  const key = resolveApiKeySync({ apiKey: extension.config.apiKey });
+  if (key === undefined) {
+    throw new Error(`Grok Bot agents need a Cursor API key. ${SIGN_IN_HINT}`);
+  }
+  return key.apiKey;
+}
+
+/** The route's `{ error }` envelope when it is one, the raw body otherwise. */
+function apiErrorMessage(text: string): string {
+  try {
+    const parsed = JSON.parse(text) as { error?: unknown; message?: unknown };
+    const message = parsed.error ?? parsed.message;
+    if (typeof message === "string" && message !== "") {
+      return message;
+    }
+  } catch {
+    // Not JSON; fall through to the raw body.
+  }
+  return text.slice(0, 300);
+}

package/src/extensions/cursor-grokbot-agents/lib/contacts.ts

@@ -0,0 +1,74 @@
+/**
+ * Who has talked to which Grok Bot agent, and how far into its transcript
+ * they have read. The tools authenticate with the serve host's one Cursor
+ * API key, so every agent is that account's; what the host keeps per
+ * principal is the read cursor, so `check` returns what the agent said
+ * since that caller last read, and a lookup by name for `check` and
+ * `interrupt`, which never create an agent the caller has not spoken to.
+ */
+
+import { z } from "zod";
+import type { ToolContext } from "../../../types.js";
+import { KeyedLock } from "./lock.js";
+
+const PREFIX = "grokbot-agents";
+
+// Type alias, not an interface: contacts flow into tool results.
+export type Contact = {
+  /** The agent's name as the backend stores it. */
+  name: string;
+  /** The hosted agent's `/v0/grokbot` session id. */
+  sessionId: string;
+  /** Newest transcript `updatedSeq` this principal has read. */
+  cursor: string;
+  firstContactAt: string;
+  lastContactAt: string;
+};
+
+const contactsSchema: z.ZodType<Contact[]> = z.array(
+  z.object({
+    name: z.string(),
+    sessionId: z.string(),
+    cursor: z.string(),
+    firstContactAt: z.string(),
+    lastContactAt: z.string(),
+  }),
+);
+
+const locks = new KeyedLock();
+
+/** Unauthenticated sessions (local dev, direct calls) share one principal. */
+export function principalOf(ctx: ToolContext): string {
+  const auth = ctx.session.auth;
+  return auth === null ? "anonymous" : `${auth.principalType}:${auth.principalId}`;
+}
+
+/** The caller's contacts, most recently spoken to first. */
+export async function listContacts(ctx: ToolContext): Promise<Contact[]> {
+  const contacts = contactsSchema.safeParse(await ctx.host.kv.get(contactsKey(principalOf(ctx))));
+  return contacts.success ? contacts.data : [];
+}
+
+/** The contact of that name, exact spelling first, then case-insensitively. */
+export function findContact(contacts: Contact[], name: string): Contact | undefined {
+  const wanted = name.trim();
+  return (
+    contacts.find(contact => contact.name === wanted) ??
+    contacts.find(contact => contact.name.toLowerCase() === wanted.toLowerCase())
+  );
+}
+
+/** Insert or replace the caller's record of one agent, newest first. */
+export async function saveContact(ctx: ToolContext, contact: Contact): Promise<void> {
+  const key = contactsKey(principalOf(ctx));
+  await locks.run(key, async () => {
+    const others = (await listContacts(ctx)).filter(
+      existing => existing.sessionId !== contact.sessionId,
+    );
+    await ctx.host.kv.put(key, [contact, ...others]);
+  });
+}
+
+function contactsKey(principal: string): string {
+  return `${PREFIX}/principals/${encodeURIComponent(principal)}`;
+}

package/src/extensions/cursor-grokbot-agents/lib/conversation.ts

@@ -0,0 +1,260 @@
+/**
+ * One exchange with a hosted Grok Bot agent, the way the grokbot runtime
+ * drives a turn: send a user message, then read the transcript until the
+ * agent's turn settles. Only `send-message` entries (what the agent delivers
+ * through SendToUser) are the reply; its internal work never appears in the
+ * transcript. Waits are bounded, so a long turn comes back as `running` and
+ * `check` picks it up from the caller's cursor.
+ *
+ * Sends and reads on one hosted agent are chained within this process, and
+ * a send waits for an in-flight turn to settle first, so a reply always
+ * attributes to the message that prompted it.
+ */
+
+import type { ToolContext } from "../../../types.js";
+import extension from "../extension.js";
+import { resolveAgentName } from "./agents.js";
+import {
+  type GrokBotAgentsBackend,
+  type GrokBotTurnStatus,
+  grokBotAgentsBackend,
+} from "./backend.js";
+import { type Contact, findContact, listContacts, saveContact } from "./contacts.js";
+import { KeyedLock } from "./lock.js";
+
+export const DEFAULT_WAIT_SECONDS = 120;
+export const MAX_WAIT_SECONDS = 600;
+
+/**
+ * Idle polls required before a turn counts as settled when the workflow
+ * never reported busy: covers the window between an accepted send and the
+ * workflow picking the signal up, which a `check` right after a short `ask`
+ * can still be inside.
+ */
+const MIN_IDLE_POLLS_WITHOUT_BUSY = 4;
+/**
+ * A session whose row is this young, and whose transcript is still empty,
+ * was created by the call that fetched it; the allowance covers clock skew
+ * between this host and the backend.
+ */
+const CREATED_WINDOW_MS = 60_000;
+/** The transcript tail of an agent nobody has spoken to. */
+const EMPTY_TRANSCRIPT_TAIL = "-1";
+
+export type ReplyStatus = "finished" | "running";
+
+// Type aliases, not interfaces: these are tool results.
+export type AskResult = {
+  agent: string;
+  sessionId: string;
+  status: ReplyStatus;
+  /** What the agent sent back, in order; absent when it sent nothing (yet). */
+  reply?: string;
+  /** Replies to earlier messages that this caller had not read yet. */
+  earlierReplies?: string[];
+  /** The account had no agent of that name; this call created an empty one. */
+  created?: true;
+  note?: string;
+};
+
+export type CheckResult = {
+  agent: string;
+  sessionId: string;
+  status: ReplyStatus;
+  reply?: string;
+  note?: string;
+};
+
+export type InterruptResult = {
+  agent: string;
+  sessionId: string;
+  interrupted: true;
+};
+
+type Replies = {
+  status: ReplyStatus;
+  deliveries: string[];
+  /** Newest `updatedSeq` consumed. */
+  cursor: string;
+};
+
+const agentLocks = new KeyedLock();
+
+export async function ask(
+  ctx: ToolContext,
+  input: { agent?: string; message: string; waitSeconds: number },
+): Promise<AskResult> {
+  const name = resolveAgentName(input.agent, extension.config.agents);
+  const backend = grokBotAgentsBackend();
+  const startedAt = Date.now();
+  const session = await backend.session(name);
+  return agentLocks.run(session.sessionId, async () => {
+    const contact = (await listContacts(ctx)).find(
+      candidate => candidate.sessionId === session.sessionId,
+    );
+    const created =
+      contact === undefined &&
+      session.latestUpdatedSeq === EMPTY_TRANSCRIPT_TAIL &&
+      session.createdAtMs >= startedAt - CREATED_WINDOW_MS;
+    const deadline = Date.now() + input.waitSeconds * 1000;
+    // A turn already in flight, from an earlier message or from the person
+    // in the app, must settle first; otherwise its deliveries would read as
+    // the reply to this message. Nothing is persisted on the way out, so
+    // `check` still returns whatever landed meanwhile.
+    const before = await collectReplies(backend, session.sessionId, {
+      cursor: contact?.cursor ?? session.latestUpdatedSeq,
+      deadline,
+      confirmIdle: false,
+    });
+    if (before.status === "running") {
+      throw new Error(
+        `"${session.name}" is still working on an earlier message; nothing was sent. Call check to read that reply, wait, or interrupt it.`,
+      );
+    }
+    await backend.send(session.sessionId, input.message);
+    const replies = await collectReplies(backend, session.sessionId, {
+      cursor: before.cursor,
+      deadline,
+      confirmIdle: true,
+    });
+    const now = ctx.now().toISOString();
+    await saveContact(ctx, {
+      name: session.name,
+      sessionId: session.sessionId,
+      cursor: replies.cursor,
+      firstContactAt: contact?.firstContactAt ?? now,
+      lastContactAt: now,
+    });
+    const notes = [
+      created
+        ? `No Grok Bot agent named "${session.name}" existed on this account, so an empty one was created. Check the name if that is unexpected.`
+        : undefined,
+      runningNote(session.name, replies.status),
+    ].filter(note => note !== undefined);
+    return {
+      agent: session.name,
+      sessionId: session.sessionId,
+      status: replies.status,
+      reply: joinReplies(replies.deliveries),
+      earlierReplies: before.deliveries.length === 0 ? undefined : before.deliveries,
+      created: created ? true : undefined,
+      note: notes.length === 0 ? undefined : notes.join(" "),
+    };
+  });
+}
+
+export async function check(
+  ctx: ToolContext,
+  input: { agent?: string; waitSeconds: number },
+): Promise<CheckResult> {
+  const contact = await knownContact(ctx, input.agent);
+  const backend = grokBotAgentsBackend();
+  return agentLocks.run(contact.sessionId, async () => {
+    // Re-read under the lock: a parallel call may have moved the cursor.
+    const current =
+      (await listContacts(ctx)).find(candidate => candidate.sessionId === contact.sessionId) ??
+      contact;
+    const replies = await collectReplies(backend, current.sessionId, {
+      cursor: current.cursor,
+      deadline: Date.now() + input.waitSeconds * 1000,
+      confirmIdle: true,
+    });
+    await saveContact(ctx, { ...current, cursor: replies.cursor });
+    return {
+      agent: current.name,
+      sessionId: current.sessionId,
+      status: replies.status,
+      reply: joinReplies(replies.deliveries),
+      note: runningNote(current.name, replies.status),
+    };
+  });
+}
+
+export async function interrupt(
+  ctx: ToolContext,
+  input: { agent?: string },
+): Promise<InterruptResult> {
+  const contact = await knownContact(ctx, input.agent);
+  await grokBotAgentsBackend().interrupt(contact.sessionId, "Interrupted from the Agent SDK.");
+  return {
+    agent: contact.name,
+    sessionId: contact.sessionId,
+    interrupted: true,
+  };
+}
+
+/**
+ * The caller's record of the named agent. Only `ask` resolves a name on the
+ * backend, because that creates an agent when none matches; the other tools
+ * reach agents the caller has already spoken to.
+ */
+async function knownContact(ctx: ToolContext, requested: string | undefined): Promise<Contact> {
+  const name = resolveAgentName(requested, extension.config.agents);
+  const contact = findContact(await listContacts(ctx), name);
+  if (contact === undefined) {
+    throw new Error(`You have not asked "${name}" anything yet; call ask first.`);
+  }
+  return contact;
+}
+
+/**
+ * Read the transcript after `cursor` until the agent's turn settles or the
+ * deadline passes. Only an empty page can settle the turn, so a backlog
+ * drains page by page first. With `confirmIdle`, an idle report may predate
+ * the workflow picking a message up, so settling takes
+ * {@link MIN_IDLE_POLLS_WITHOUT_BUSY} idle polls unless the turn was seen
+ * busy; without it, the first idle report settles.
+ */
+async function collectReplies(
+  backend: GrokBotAgentsBackend,
+  sessionId: string,
+  options: { cursor: string; deadline: number; confirmIdle: boolean },
+): Promise<Replies> {
+  const deliveries: string[] = [];
+  let cursor = options.cursor;
+  let sawBusy = false;
+  let idlePolls = 0;
+  while (true) {
+    const page = await backend.entries(sessionId, cursor);
+    cursor = page.latestUpdatedSeq;
+    for (const entry of page.entries) {
+      if (entry.kind === "send-message" && entry.text !== undefined) {
+        deliveries.push(entry.text);
+      }
+    }
+    const busy = isBusy(page.turn);
+    if (busy) {
+      sawBusy = true;
+    }
+    if (page.entries.length === 0 && !busy && page.turn.idle) {
+      idlePolls += 1;
+      if (sawBusy || !options.confirmIdle || idlePolls >= MIN_IDLE_POLLS_WITHOUT_BUSY) {
+        return { status: "finished", deliveries, cursor };
+      }
+    }
+    if (Date.now() >= options.deadline) {
+      return { status: "running", deliveries, cursor };
+    }
+    await sleep(extension.config.pollIntervalMs);
+  }
+}
+
+function isBusy(turn: GrokBotTurnStatus): boolean {
+  return turn.inFlight || turn.queued > 0;
+}
+
+function joinReplies(deliveries: string[]): string | undefined {
+  return deliveries.length === 0 ? undefined : deliveries.join("\n\n");
+}
+
+function runningNote(name: string, status: ReplyStatus): string | undefined {
+  return status === "running"
+    ? `"${name}" is still replying. Call check with the same agent to keep waiting; a reply so far, if any, is above.`
+    : undefined;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/extensions/cursor-grokbot-agents/lib/inputs.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { AGENT_NAME_MAX_LENGTH } from "../extension.js";
+import { DEFAULT_WAIT_SECONDS, MAX_WAIT_SECONDS } from "./conversation.js";
+
+export const agentName: z.ZodOptional<z.ZodString> = z
+  .string()
+  .max(AGENT_NAME_MAX_LENGTH)
+  .optional()
+  .describe(
+    "The Grok Bot agent's name, as shown in the Grok Bot app. With agents configured, one of those; optional when exactly one is configured.",
+  );
+
+export const waitSeconds: z.ZodDefault<z.ZodNumber> = z
+  .number()
+  .int()
+  .min(0)
+  .max(MAX_WAIT_SECONDS)
+  .default(DEFAULT_WAIT_SECONDS)
+  .describe(
+    `How long to wait for the reply before returning status "running" (default ${DEFAULT_WAIT_SECONDS}, max ${MAX_WAIT_SECONDS}). 0 returns after one look.`,
+  );

package/src/extensions/cursor-grokbot-agents/lib/lock.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-key chaining of async work. `host.kv` has no compare-and-swap, and a
+ * model that talks to two agents in one turn calls these tools in parallel,
+ * so read-modify-writes of one principal's records queue up here. The same
+ * chain keeps one hosted agent's sends and reads from interleaving within
+ * this process, so a reply attributes to the message that prompted it.
+ */
+export class KeyedLock {
+  private readonly chains = new Map<string, Promise<void>>();
+
+  run<T>(key: string, task: () => Promise<T>): Promise<T> {
+    const previous = this.chains.get(key) ?? Promise.resolve();
+    const run = previous.then(task, task);
+    const settled = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.chains.set(key, settled);
+    void settled.then(() => {
+      if (this.chains.get(key) === settled) {
+        this.chains.delete(key);
+      }
+    });
+    return run;
+  }
+}

package/src/extensions/cursor-grokbot-agents/skills/consult.md

@@ -0,0 +1,40 @@
+---
+description: "Talk to your Grok Bot agents: when to bring one in, how to write a message it can act on alone, and how to wait for, read, and interrupt its reply."
+---
+
+# Consulting a Grok Bot agent
+
+Bring a Grok Bot agent in when the person set one up for the job: a specialist with its own instructions, memory, and tools, such as one that decides whether an outdoor plan survives a forecast or one that keeps a household's calendar. Answer questions you can answer yourself.
+
+The tools below are this extension's; they appear under its mount namespace, as `<namespace>__ask` and so on. Every agent is addressed by its `agent` name, as it appears in the Grok Bot app. When exactly one agent is configured, `agent` can be omitted.
+
+## Write for a stranger
+
+Your message lands in the person's own conversation with that agent, the same one they see in the app. The agent does not see this conversation, your tools, or your earlier results. Say who is asking and why, paste the facts it needs rather than referring to them, and say what you want back and in what shape. One complete message beats a back-and-forth.
+
+## Ask
+
+Call `ask` with the `agent` and the `message`. It sends the message and waits up to `wait_seconds` for the agent's turn to finish. The result carries `status`, the `reply` (everything the agent sent back during that turn, in order), and `sessionId`.
+
+- `status: "finished"`: the turn is over; `reply` is the whole answer. No `reply` means the agent finished without sending anything.
+- `status: "running"`: the agent is still working. Call `check` with the same `agent` to keep waiting; whatever it had sent so far is already in `reply`.
+
+If `earlierReplies` is present, the agent had answered earlier messages that nobody read yet; pass them on when they matter, and do not mistake them for the reply to this message.
+
+If `created` is true, no agent of that name existed on the account and an empty one was created. Tell the person and check the spelling before asking it anything else.
+
+If `ask` fails because an agent of that name already exists in the Grok Bot app, nothing was created and nothing was sent. Tell the person. Do not invent a different name to get around it.
+
+If `ask` refuses because the agent is still working on an earlier message, nothing was sent. If you have already asked that agent, call `check` to read the reply, then ask again; use `interrupt` when the earlier work should stop. On first contact, `check` and `interrupt` cannot address the agent yet, so tell the person it is busy, wait for the existing turn to finish in the Grok Bot app, and retry `ask`.
+
+## Wait for a long reply
+
+Call `check` with the `agent`. It returns what the agent has sent since you last read, and `status: "running"` while the turn is still going. Pass `wait_seconds: 0` for a single look. Check when you need the answer, not in a tight loop; a long task can take minutes.
+
+## Interrupt
+
+Call `interrupt` with the `agent` to stop its current turn. The agent keeps its conversation, so a later `ask` continues from there.
+
+## Which agents
+
+`list` returns the agents configured for you, with what each is for, and the ones you have already asked. Names outside the configured set are refused; with no set configured, any name works, and an unknown name creates an agent.

package/src/extensions/cursor-grokbot-agents/tools/ask.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import extension from "../extension.js";
+import { ask as askAgent } from "../lib/conversation.js";
+import { agentName, waitSeconds } from "../lib/inputs.js";
+
+const ask: ToolDefinition = defineTool({
+  description:
+    'Send a message to one of your Grok Bot agents and wait for its reply. The message lands in your own conversation with that agent, which does not see this one, so include everything it needs. Long turns return status "running": call check to keep waiting.',
+  effect: "write",
+  needsApproval: () => extension.config.needsApproval,
+  inputSchema: z.object({
+    agent: agentName,
+    message: z
+      .string()
+      .min(1)
+      .describe(
+        "What to tell or ask the agent. Self-contained: who is asking, the facts it needs, and what you want back.",
+      ),
+    wait_seconds: waitSeconds,
+  }),
+  async execute(input, ctx) {
+    return askAgent(ctx, {
+      agent: input.agent,
+      message: input.message,
+      waitSeconds: input.wait_seconds,
+    });
+  },
+});
+
+export default ask;

package/src/extensions/cursor-grokbot-agents/tools/check.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { check as checkAgent } from "../lib/conversation.js";
+import { agentName, waitSeconds } from "../lib/inputs.js";
+
+const check: ToolDefinition = defineTool({
+  description:
+    'Wait for, or poll, the reply of a Grok Bot agent you asked: everything it has sent since you last read, and whether it is still working. Returns status "running" to keep waiting; pass wait_seconds 0 for a single look.',
+  // Reading advances the caller's cursor, which their other sessions read
+  // back, so a dry run answers this instead of running it.
+  effect: "write",
+  inputSchema: z.object({
+    agent: agentName,
+    wait_seconds: waitSeconds,
+  }),
+  async execute(input, ctx) {
+    return checkAgent(ctx, {
+      agent: input.agent,
+      waitSeconds: input.wait_seconds,
+    });
+  },
+});
+
+export default check;