@cursor/july 0.1.68 → 0.1.73

package/src/internal/terminal-style.ts

@@ -16,6 +16,14 @@ export interface TerminalPalette {
 }
 
 const IDENTITY = (s: string): string => s;
+const ESC = "\u001b";
+const BEL = "\u0007";
+const ANSI_CSI = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
+/** OSC 8 hyperlinks: `ESC ] 8 ; params ; uri BEL` (or ST). */
+const OSC_8 = new RegExp(
+  `${ESC}\\]8;[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`,
+  "g"
+);
 
 const PLAIN: TerminalPalette = {
   dim: IDENTITY,
@@ -42,7 +50,7 @@ export function makePalette(enabled: boolean): TerminalPalette {
     (s: string): string =>
       `\u001b[${code}m${s}\u001b[0m`;
   return {
-    dim: wrap("2"),
+    dim: (s: string) => (hasAnsiStyling(s) ? s : wrap("2")(s)),
     bold: wrap("1"),
     cyan: wrap("36"),
     green: wrap("32"),
@@ -62,6 +70,64 @@ export function stderrPalette(): TerminalPalette {
   return makePalette(colorEnabledFor(process.stderr));
 }
 
+/** Visible column count, ignoring CSI color/style and OSC 8 hyperlinks. */
+export function visibleWidth(text: string): number {
+  return text.replace(OSC_8, "").replace(ANSI_CSI, "").length;
+}
+
+/** True when `text` already carries CSI styling or OSC 8 (do not wrap again). */
+export function hasAnsiStyling(text: string): boolean {
+  return text.includes("\u001b[") || text.includes("\u001b]");
+}
+
+/**
+ * Clickable terminal hyperlink (OSC 8). The URI is the click target; `label`
+ * is what the user sees. `visibleWidth` ignores the OSC wrapper.
+ */
+export function terminalHyperlink(
+  url: string,
+  label: string,
+  enabled: boolean = colorEnabledFor()
+): string {
+  if (!enabled) {
+    return label;
+  }
+  return `\u001b]8;;${url}\u0007\u001b[4m${label}\u001b[24m\u001b]8;;\u0007`;
+}
+
+/**
+ * Unicode box around `lines`. `color` wraps the whole box (borders + body)
+ * so a warning panel can be yellow without per-line prefixes.
+ */
+export function formatTerminalBox(
+  lines: readonly string[],
+  options?: {
+    color?: (s: string) => string;
+    minWidth?: number;
+    padding?: number;
+  }
+): string {
+  const color = options?.color ?? IDENTITY;
+  const padding = options?.padding ?? 1;
+  const contentWidth = Math.max(
+    options?.minWidth ?? 0,
+    ...lines.map((line) => visibleWidth(line)),
+    1
+  );
+  const inner = contentWidth + padding * 2;
+  const padLine = (line: string): string => {
+    const extra = contentWidth - visibleWidth(line);
+    return `│${" ".repeat(padding)}${line}${" ".repeat(padding + extra)}│`;
+  };
+  const paint = (line: string): string => color(line);
+  const box = [
+    paint(`╭${"─".repeat(inner)}╮`),
+    ...lines.map((line) => paint(padLine(line))),
+    paint(`╰${"─".repeat(inner)}╯`),
+  ].join("\n");
+  return box;
+}
+
 /** Wipe the terminal before a `dev` Enter-to-restart cycle. */
 export function clearTerminal(
   stream: NodeJS.WriteStream = process.stdout

package/src/internal/workspace.ts

@@ -19,6 +19,7 @@ import {
   symlink,
   writeFile,
 } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join, parse, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH } from "../files.js";
@@ -272,6 +273,11 @@ export async function isNestedInGitRepo(dir: string): Promise<boolean> {
   return false;
 }
 
+/** Default harness parent for a nested-git agent project. */
+export function defaultLocalHarnessCwd(dirName: string): string {
+  return join(homedir(), ".cache", "agent-serve", dirName);
+}
+
 /**
  * Give a session workspace its own git root so the harness roots *there*
  * rather than at the enclosing repo (see {@link isNestedInGitRepo}). Without

package/src/tools.ts

@@ -85,6 +85,11 @@ type ServerToolConfig<TSchema> = {
   description: string;
   execution?: "server";
   inputSchema?: TSchema;
+  /**
+   * JSON Schema for the tool's structured output (zod converted at
+   * discovery, never validated against). Advertised when declared.
+   */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   needsApproval?: ToolNeedsApproval<ToolInput<TSchema>>;
   execute: (
     input: ToolInput<TSchema>,
@@ -97,6 +102,8 @@ type AgentToolConfig<TSchema> = {
   description: string;
   execution: "agent";
   inputSchema?: TSchema;
+  /** Output JSON Schema; advertised when declared, never validated against. */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   /**
    * Shell script written into the session workspace. Receives a JSON
    * object on stdin and should print the result on stdout.

package/src/types.ts

@@ -347,9 +347,13 @@ export interface AgentLocalOptions {
   /**
    * Default local harness cwd parent. Absolute, or relative to the agent
    * project root. Each session uses `<cwd>/<sessionId>` unless a per-send
-   * {@link SendMessageOptions.workspaceDir} overrides it. Prefer a path
-   * outside large monorepos so Cursor `project` settings do not inherit
-   * ambient `AGENTS.md` / `.cursor` rules.
+   * {@link SendMessageOptions.workspaceDir} overrides it.
+   *
+   * When omitted, a project nested in another git repo (a monorepo package)
+   * defaults to `~/.cache/agent-serve/<dir>` so Cursor does not load the
+   * enclosing checkout's AGENTS.md, rules, skills, or MCP servers. A
+   * standalone git root keeps the in-project session workspace. Point this
+   * at a checkout when the agent must inherit that tree.
    */
   cwd?: string;
   /**
@@ -428,7 +432,17 @@ export type ToolResultValue =
  */
 export type ToolExecuteResult =
   | ToolResultValue
-  | { content: ToolResultContent[]; isError?: boolean };
+  | {
+      content: ToolResultContent[];
+      isError?: boolean;
+      /**
+       * Structured result for tools that declare an `outputSchema`: MCP
+       * clients require `structuredContent` on calls to schema-declaring
+       * tools. Plain-object returns get it filled in automatically; the
+       * envelope form (needed for images or `isError`) sets it here.
+       */
+      structuredContent?: JsonObject;
+    };
 
 /** Repo-agnostic GitHub client on the agent-serve host. */
 export interface HostGitHubClient {
@@ -456,6 +470,7 @@ export interface HostMcpToolInfo {
   name: string;
   description?: string;
   inputSchema?: JsonObject;
+  outputSchema?: JsonObject;
 }
 
 export interface HostMcpCallResult {
@@ -861,6 +876,13 @@ export interface ToolConfig<TInput> {
    * JSON object.
    */
   inputSchema?: z.ZodType<TInput> | JsonSchemaObject;
+  /**
+   * JSON Schema for the tool's structured output (`Tool.outputSchema` from
+   * the MCP spec), as a zod schema (converted, never validated against) or a
+   * plain JSON Schema object. Advertised when declared and omitted
+   * otherwise — results are not validated against it.
+   */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   /**
    * When true (or when the predicate returns true), the host parks the
    * in-flight tool call until a human approves or denies via
@@ -889,6 +911,7 @@ export interface ToolDefinition extends BrandedDefinition<"tool"> {
   readonly description: string;
   readonly execution?: ToolExecution;
   readonly inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+  readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly needsApproval?: ToolNeedsApproval<never>;
   readonly execute?: (
     input: never,
@@ -1036,6 +1059,8 @@ export function isSymbolicConnectionTransport(
 export type InlineStdioToolConfig = {
   description: string;
   inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+  /** Output JSON Schema (zod converted, never validated); advertised when declared. */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   execute: (input: JsonObject) => unknown | Promise<unknown>;
 };
 
@@ -2448,6 +2473,8 @@ export interface DiscoveredTool {
   description: string;
   /** JSON Schema advertised to the model. */
   inputSchema: JsonSchemaObject;
+  /** Output JSON Schema, advertised only when the tool declares one. */
+  outputSchema?: JsonSchemaObject;
   /** Where the tool body runs. Defaults to `"server"`. */
   execution: ToolExecution;
   /**
@@ -2629,6 +2656,7 @@ export interface AgentProjectInfo {
     name: string;
     transport: string;
     hostOnly?: boolean;
+    advertiseTools?: boolean;
     /**
      * Present only for `cursorAccount` connections: the connector-name
      * allowlist, or `"*"` for every connected server. Structured twin of the

package/templates/agentic-owners/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep", "glob", "ls"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "agentic-owners"),
   },
 });

package/templates/demo/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "demo"),
   },
 });

package/templates/security-reviewer/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "security-reviewer"),
   },
 });

package/templates/triage/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep", "glob", "ls"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "triage"),
   },
 });