@cursor/july 0.1.104 → 0.1.105

package/src/internal/tenant-slack/relay.ts

@@ -109,13 +109,22 @@ export async function postRelaySlackMessage(args: {
   resolve?: () => RelaySlackPostTarget | undefined;
   fetchImpl?: typeof fetch;
   timeoutMs?: number;
+  /** Diagnostic sink; defaults to `console.info`. */
+  log?: (line: string) => void;
 }): Promise<RelaySlackPostResult> {
   const channel = args.channel.trim();
+  const log = args.log ?? ((line: string) => console.info(line));
   if (channel === "") {
+    log(
+      `[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid}: empty channel`
+    );
     return { ok: false, channel, status: 0, error: "empty channel" };
   }
   const target = (args.resolve ?? resolveRelaySlackTarget)();
   if (target === undefined) {
+    log(
+      `[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid} channel=${channel}: no Cursor credential resolved (CURSOR_API_KEY / pod credential absent)`
+    );
     return {
       ok: false,
       channel,
@@ -128,6 +137,11 @@ export async function postRelaySlackMessage(args: {
     baseUrl: target.relayBaseUrl,
     automationUuid: args.automationUuid,
   });
+  const messageChars = args.message.length;
+  log(
+    `[agent-sdk-slack-relay-client] POST ${url} channel=${channel} messageChars=${String(messageChars)} truncated=${String(messageChars > AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS)} threaded=${String(args.threadTs !== undefined)} timeoutMs=${String(args.timeoutMs ?? DEFAULT_TIMEOUT_MS)}`
+  );
+  const startedAt = Date.now();
   let response: Response;
   try {
     response = await fetchImpl(url, {
@@ -145,6 +159,9 @@ export async function postRelaySlackMessage(args: {
       signal: AbortSignal.timeout(args.timeoutMs ?? DEFAULT_TIMEOUT_MS),
     });
   } catch (error) {
+    log(
+      `[agent-sdk-slack-relay-client] request failed before a response channel=${channel} automationUuid=${args.automationUuid} elapsedMs=${String(Date.now() - startedAt)}: ${describeError(error)}`
+    );
     return { ok: false, channel, status: 0, error: describeError(error) };
   }
   let body: unknown;
@@ -158,16 +175,23 @@ export async function postRelaySlackMessage(args: {
       ? (body as Record<string, unknown>)
       : {};
   if (!response.ok || record.ok !== true) {
+    const error =
+      typeof record.error === "string" && record.error !== ""
+        ? record.error
+        : `relay responded ${response.status}`;
+    log(
+      `[agent-sdk-slack-relay-client] relay denied channel=${channel} automationUuid=${args.automationUuid} status=${String(response.status)} bodyOk=${String(record.ok)} elapsedMs=${String(Date.now() - startedAt)}: ${error}`
+    );
     return {
       ok: false,
       channel,
       status: response.status,
-      error:
-        typeof record.error === "string" && record.error !== ""
-          ? record.error
-          : `relay responded ${response.status}`,
+      error,
     };
   }
+  log(
+    `[agent-sdk-slack-relay-client] relay posted channel=${typeof record.channel === "string" ? record.channel : channel} automationUuid=${args.automationUuid} status=${String(response.status)} ts=${typeof record.ts === "string" ? record.ts : "<none>"} elapsedMs=${String(Date.now() - startedAt)}`
+  );
   return {
     ok: true,
     channel: typeof record.channel === "string" ? record.channel : channel,

package/src/internal/workspace-sync.ts

@@ -1,10 +1,10 @@
 /**
- * Sync `agent/sandbox/workspace/**` seed files onto an Agent Store so
- * cloud-runtime turns read them from the store mount (the first cloud prompt
- * names the directory; see `buildCloudWorkspaceSection`). Hosted deployments
- * write store-root `workspace/<path>`. Local `serve`/`run` with
- * `runtime: "cloud"` writes `agent-serve/<agent>/workspace/<path>` on the
- * USER store.
+ * Sync workspace trees onto an Agent Store so cloud-runtime turns read
+ * them from the store mount. Authored `agent/sandbox/workspace/**` seeds
+ * land at store-root `workspace/<path>` (see `buildCloudWorkspaceSection`).
+ * Per-turn `workspaceFiles` land at `sessions/<sessionId>/workspace/<path>`
+ * (see `buildCloudSessionWorkspaceSection`). Personal-key local+cloud
+ * nests both under `agent-serve/<agent>/`.
  */
 
 import { readFile } from "node:fs/promises";
@@ -13,6 +13,15 @@ import { MEMORY_DIR_NAME } from "../memory.js";
 import type { SeedFile } from "../types.js";
 import { mirrorToStore, storeRelPath } from "./store-mirror.js";
 
+export type WorkspaceFileBody =
+  | string
+  | { encoding: "base64"; data: string; mimeType?: string };
+
+/** Path or encoding that can never land. Distinct from a store outage. */
+export class WorkspaceFileRefusal extends Error {
+  override readonly name = "WorkspaceFileRefusal";
+}
+
 /**
  * Mirror the seed tree onto the store at its authored relative paths and
  * delete keys no seed claims so redeploys drop removed files. Every seed
@@ -30,7 +39,7 @@ export async function syncWorkspaceToStore(args: {
   for (const seed of args.seedFiles) {
     desired.set(
       agentStoreKeys.workspaceFile(
-        seedRelPath(seed.relativePath),
+        workspaceRelPath(seed.relativePath),
         workspacePrefix
       ),
       await readFile(seed.sourcePath)
@@ -39,17 +48,80 @@ export async function syncWorkspaceToStore(args: {
   await mirrorToStore({ sink: args.sink, prefix: workspacePrefix, desired });
 }
 
+/**
+ * Replace the session workspace prefix with this turn's `workspaceFiles`.
+ * Keys the map does not claim are deleted so a later send cannot leave a
+ * stale `pr.json`. Every path validates before the store is touched.
+ * Returns the relative paths that landed, in send order.
+ */
+export async function syncSessionWorkspaceFiles(args: {
+  sink: FileSink;
+  files: Record<string, WorkspaceFileBody>;
+  workspacePrefix: string;
+}): Promise<string[]> {
+  const desired = new Map<string, Uint8Array>();
+  const relPaths: string[] = [];
+  for (const [relativePath, contents] of Object.entries(args.files)) {
+    const rel = workspaceRelPath(relativePath);
+    desired.set(
+      agentStoreKeys.workspaceFile(rel, args.workspacePrefix),
+      workspaceFileBytes(relativePath, contents)
+    );
+    relPaths.push(rel);
+  }
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: args.workspacePrefix,
+    desired,
+  });
+  return relPaths;
+}
+
+/** Delete every key under the session workspace prefix. */
+export async function wipeSessionWorkspace(args: {
+  sink: FileSink;
+  workspacePrefix: string;
+}): Promise<void> {
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: args.workspacePrefix,
+    desired: new Map(),
+  });
+}
+
 /**
  * Same reservation as local materialization's `resolveWorkspaceWritePath`:
- * `memory/` is the shared cross-session journal, so a seed under it fails
- * the sync exactly as it fails a local first turn.
+ * `memory/` is the shared cross-session journal, so a seed or send under it
+ * fails the sync exactly as it fails a local first turn.
  */
-function seedRelPath(relPath: string): string {
-  const rel = storeRelPath(relPath, "workspace file");
+function workspaceRelPath(relPath: string): string {
+  let rel: string;
+  try {
+    rel = storeRelPath(relPath, "workspace file");
+  } catch (error) {
+    throw new WorkspaceFileRefusal(
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   if (rel.split("/", 1)[0] === MEMORY_DIR_NAME) {
-    throw new Error(
+    throw new WorkspaceFileRefusal(
       `"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`
     );
   }
   return rel;
 }
+
+function workspaceFileBytes(
+  relativePath: string,
+  contents: WorkspaceFileBody
+): Uint8Array {
+  if (typeof contents === "string") {
+    return new TextEncoder().encode(contents);
+  }
+  if (contents.encoding === "base64") {
+    return new Uint8Array(Buffer.from(contents.data, "base64"));
+  }
+  throw new WorkspaceFileRefusal(
+    `Unsupported workspace file encoding for ${relativePath}`
+  );
+}

package/src/internal/workspace.ts

@@ -80,6 +80,26 @@ export function buildCloudWorkspaceSection(dir: string): string {
   ].join("\n");
 }
 
+/**
+ * Per-turn preamble for cloud `workspaceFiles` after they land on the
+ * session store prefix (see `syncSessionWorkspaceFiles`). Omitted when
+ * the sync did not land.
+ *
+ * Same shared Agent Store mount as authored seeds — the session path is
+ * replace-per-send / task-end wipe lifetime, not a separate mount ACL.
+ */
+export function buildCloudSessionWorkspaceSection(
+  dir: string,
+  relPaths: readonly string[]
+): string {
+  const listed = relPaths.map((path) => `\`${path}\``).join(", ");
+  return [
+    "## Session workspace files",
+    "",
+    `This turn's workspace files live at \`${dir}\` on this machine (${listed}). Read them with your normal file tools. They sit on the same shared Agent Store mount as authored workspace seeds; the session directory is replaced on the next send for this session, and task sessions remove it when they finish.`,
+  ].join("\n");
+}
+
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;

package/src/types.ts

@@ -1926,8 +1926,9 @@ export interface SessionRecord {
    */
   workspaceOverride?: string;
   /**
-   * One-shot files to write into the harness cwd before the next turn
-   * (see {@link SendMessageOptions.workspaceFiles}). Cleared after apply.
+   * One-shot files for the next turn (see {@link SendMessageOptions.workspaceFiles}).
+   * Local turns write them into the harness cwd. Cloud turns sync them onto
+   * the session Agent Store prefix. Cleared after apply.
    */
   pendingWorkspaceFiles?: Record<
     string,
@@ -2112,12 +2113,12 @@ export interface SendMessageOptions {
    */
   workspaceDir?: string;
   /**
-   * Relative path → contents written into the session harness cwd after
-   * scaffold materialize and before the next turn. On create, queued for
-   * the first turn; on resume, replaces any pending files. Prefer this
-   * over {@link workspaceDir} when you only need to inject a few
-   * host-prepared files (skills/AGENTS.md still land in the normal
-   * session workspace). Values may be utf8 strings or
+   * Relative path → contents for the next turn. Local turns write them into
+   * the harness cwd after scaffold materialize. Cloud turns sync them onto
+   * the session Agent Store prefix instead of the VM working directory. On
+   * create, queued for the first turn; on resume, merged into any pending
+   * files. Prefer this over {@link workspaceDir} when you only need to
+   * inject a few host-prepared files. Values may be utf8 strings or
    * `{ encoding: "base64", data }` blobs (Slack attachments, binary docs).
    */
   workspaceFiles?: Record<

package/templates/grokbot-agents/README.md

@@ -0,0 +1,26 @@
+# Grok Bot agents
+
+Consults the Grok Bot agents you name. This agent stays in its own
+conversation and reports the reply.
+
+```bash
+npx @cursor/july init ./grokbot --template grokbot-agents
+```
+
+`init` asks for the names shown in the Grok Bot app. Skip the prompt
+with `--var agents="Plan Keeper, Chief of Staff"`.
+
+## Run
+
+```bash
+agent-sdk login
+agent-sdk dev
+```
+
+In the playground, ask it to talk to one of the names you entered. A
+name outside the list is refused.
+
+## Edit
+
+- `agent/extensions/grokbot.ts`: who it may talk to
+- `agent/instructions.md`: when to consult them

package/templates/grokbot-agents/agent/agent.ts

@@ -0,0 +1,6 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  // Empty allowlist: only the mounted Grok Bot tools.
+  tools: [],
+});

package/templates/grokbot-agents/agent/extensions/grokbot.ts

@@ -0,0 +1,5 @@
+import cursorGrokBotAgents from "@cursor/july/extensions/cursor-grokbot-agents";
+
+export default cursorGrokBotAgents({
+  agents: ["Plan Keeper"],
+});

package/templates/grokbot-agents/agent/instructions.md

@@ -0,0 +1,7 @@
+# Grok Bot agents
+
+Consult the Grok Bot agents named in `agent/extensions/grokbot.ts`. Stay in this conversation and report the reply.
+
+When someone asks who you can talk to, call `grokbot__list`. Do not send a message.
+
+When the question belongs to one of those agents, use the consult skill. A name outside the list is refused.

package/templates/grokbot-agents/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/grokbot-agents/evals/grokbot-agents.eval.ts

@@ -0,0 +1,18 @@
+import { defineEval } from "@cursor/july/evals";
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "list",
+      description: "Asked who it can talk to, it lists and does not send.",
+      async test(t) {
+        await t.send("Who can you talk to? List them. Do not message anyone.");
+        t.succeeded();
+        t.calledTool("grokbot__list");
+        t.notCalledTool("grokbot__ask");
+        t.notCalledTool("grokbot__interrupt");
+      },
+    },
+  ],
+});

package/templates/grokbot-agents/init.json

@@ -0,0 +1,18 @@
+{
+  "questions": [
+    {
+      "id": "agents",
+      "prompt": "Which Grok Bot agents may this agent talk to?",
+      "hint": "Comma-separated names, as shown in the Grok Bot app.",
+      "placeholder": "Plan Keeper, Chief of Staff"
+    }
+  ],
+  "replace": [
+    {
+      "file": "agent/extensions/grokbot.ts",
+      "find": "[\"Plan Keeper\"]",
+      "answer": "agents",
+      "as": "json-array"
+    }
+  ]
+}

package/templates/grokbot-agents/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "grokbot-agents",
+  "private": true,
+  "type": "module",
+  "description": "Consults the Grok Bot agents you name.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/grokbot-agents/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}