@cursor/july 0.1.102 → 0.1.104

package/src/index.ts

@@ -51,44 +51,63 @@ export {
   publicEndpoint,
 } from "./channels.js";
 export { defineConnection } from "./connections.js";
-export type {
-  ContinuationBuiltin,
-  ContinuationClaim,
-  ContinuationIdentity,
-  ContinuationSelector,
-  ConversationType,
-  MailboxContinuation,
-  ParsedContinuation,
-} from "./continuation.js";
-export {
-  BUILTINS,
-  bindMailboxContinuationSend,
-  CONTINUATION_SELECTORS,
-  continuationSource,
-  defaultContinuationSelector,
-  extractContinuation,
-  formatConversationKey,
-  handshakeContinuation,
-  isContinuationSelector,
-  mintClaim,
-  normalizeIdentity,
-  parseContinuationSelector,
-  resolveContinuation,
-  resolveV2Key,
-  stampMailboxContinuation,
-  V2EngineError,
-} from "./continuation.js";
 export {
   cursorPlugin,
   defineExtension,
+  disable,
+  disableAB,
+  disableArtifacts,
+  disableChannel,
   disableConnection,
+  disableHook,
+  disableInstructions,
+  disableSchedule,
+  disableSkill,
+  disableSubagent,
   disableTool,
 } from "./extensions.js";
+export type {
+  DirEntry,
+  EditQuery,
+  EditResult,
+  FileInfo,
+  FileSystem,
+  GrepQuery,
+  GrepResult,
+  SearchQuery,
+  SearchResult,
+} from "./filesystem.js";
+export {
+  DeleteNotSupportedError,
+  EditError,
+  emptyFs,
+  FileNotFoundError,
+  hostFs,
+  InvalidGrepPatternError,
+  isFileNotFoundError,
+  NoMountError,
+  overlayFs,
+  PathError,
+  ReadOnlyMountError,
+  strReplaceOnFileSystem,
+  tempFs,
+  unionFs,
+  WriteFailedError,
+} from "./filesystem.js";
 export { defineHook } from "./hooks.js";
 export {
   InvalidAsOfError,
   VacuousTimeArgsError,
 } from "./internal/as-of.js";
+export type {
+  ContinuationBuiltin,
+  ContinuationClaim,
+  ContinuationIdentity,
+  ContinuationSelector,
+  ConversationType,
+  MailboxContinuation,
+  ParsedContinuation,
+} from "./internal/continuation-identity.js";
 export type { LoadAgentProjectOptions } from "./internal/discovery.js";
 export {
   formatDiagnostics,
@@ -144,7 +163,7 @@ export type {
   OtelDefinition,
   OtelExporterConfig,
 } from "./otel.js";
-export { defineOtel } from "./otel.js";
+export { defineOtel, resolveOtelDefinition } from "./otel.js";
 export type { PromptTag } from "./prompt.js";
 export { prompt } from "./prompt.js";
 export type {
@@ -160,6 +179,7 @@ export type {
   ReminderTarget,
   ReminderUntilContext,
 } from "./reminders.js";
+export { defineResult } from "./result.js";
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
 export type {

package/src/internal/ab-snapshot.ts

@@ -89,9 +89,6 @@ export async function buildABSnapshot(
   input: BuildABSnapshotInput
 ): Promise<ABSnapshot> {
   const experiments = input.experiments;
-  const experimentByName = new Map(
-    experiments.map((experiment) => [experiment.name, experiment])
-  );
 
   const armTotals = new Map<
     string,

package/src/internal/advertise-tools.ts

@@ -48,6 +48,7 @@ import {
   type ToolEffect,
 } from "../types.js";
 import { brandDefinition } from "./brand.js";
+import { describeError } from "./describe-error.js";
 import type { HostMcpOneOff } from "./mcp-host.js";
 import {
   sanitizeMcpToolName,
@@ -379,7 +380,3 @@ export function formatMcpToolResult(
     ? JSON.stringify(result.structuredContent, null, 2)
     : "(empty result)";
 }
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/internal/authored-alias-hooks.ts

@@ -4,20 +4,12 @@
  * thread — keep this module dependency-free).
  *
  * Authored files import the framework by bare specifier. On compiled runs the
- * CLI pins every public package name onto the running `dist/` entries via
- * `directAliases` so channel-option WeakMaps stay single-copy:
- *
- * - `@anysphere/agent-serve[/subpath]` (historical monorepo name; not on npm)
- * - `@cursor/july[/subpath]` (published name)
- * - `@cursor/agentkit[/subpath]` (future public name)
- *
- * Preferring a project's own `node_modules` (or tsx tsconfig paths that map
- * onto this package's `src/`) would load a second module instance and break
+ * CLI pins `@cursor/july[/subpath]` onto its own entry files via
+ * `directAliases` so channel-option WeakMaps stay single-copy. Preferring a
+ * project's own `node_modules` (or tsx tsconfig paths that map onto this
+ * package's `src/`) would load a second module instance and break
  * `getGitHubChannelOptions` / continuation stamping / hosted-delivery.
  *
- * `fallbackAliases` remains for tests and any future soft remap; production
- * registration leaves it empty.
- *
  * A separate case is first-party factory agents that relative-import this
  * package's `src/` from a monorepo checkout. Hosted engines `npm install`
  * only the agent directory, so files under `packages/agent-serve/src` have
@@ -28,12 +20,10 @@
 // Null-prototype copies so specifiers like "constructor" or "__proto__"
 // can never resolve to inherited Object.prototype members.
 let directAliases = toNullProtoMap({});
-let fallbackAliases = toNullProtoMap({});
 let sourceTreeFallbackParentURL: string | undefined;
 
 export interface AuthoredAliasHookData {
   directAliases: Record<string, string>;
-  fallbackAliases: Record<string, string>;
   /**
    * `file:` URL of the running `@cursor/july` package.json. Bare imports
    * from monorepo `packages/agent-serve/` source retry against this parent
@@ -50,7 +40,6 @@ function toNullProtoMap(
 
 export function initialize(data: AuthoredAliasHookData): void {
   directAliases = toNullProtoMap(data.directAliases);
-  fallbackAliases = toNullProtoMap(data.fallbackAliases);
   const parent = data.sourceTreeFallbackParentURL;
   sourceTreeFallbackParentURL =
     typeof parent === "string" && parent !== "" ? parent : undefined;
@@ -76,12 +65,6 @@ export function resolve(
   if (direct !== undefined) {
     return { url: direct, shortCircuit: true };
   }
-  const fallback = fallbackAliases[specifier];
-  if (fallback !== undefined) {
-    return Promise.resolve()
-      .then(() => nextResolve(specifier, context))
-      .catch(() => ({ url: fallback, shortCircuit: true }));
-  }
   if (
     sourceTreeFallbackParentURL !== undefined &&
     isBarePackageSpecifier(specifier) &&

package/src/internal/authored-loaders.ts

@@ -8,9 +8,8 @@
  * ESM loader itself on startup.
  *
  * On compiled runs it additionally registers alias hooks so authored bare
- * imports of the framework resolve against the running package's `dist/` —
- * `@anysphere/agent-serve[/x]`, `@cursor/july[/x]`, and `@cursor/agentkit[/x]`
- * all short-circuit to the same files the CLI loaded. Channel option WeakMaps
+ * imports of the framework (`@cursor/july[/x]`) short-circuit to the same
+ * files the CLI loaded. Channel option WeakMaps
  * (`getGitHubChannelOptions`, …) require that identity; letting tsx path-map
  * or a second install win loads a duplicate module and breaks continuation /
  * hosted-delivery lookups. Bare npm deps from monorepo `packages/agent-serve/`
@@ -25,19 +24,17 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { AuthoredAliasHookData } from "./authored-alias-hooks.js";
 import {
-  AGENTKIT_PACKAGE_NAME,
-  AUTHORING_ENTRY_FILES,
   CLI_COMMAND_NAME,
+  frameworkAliases,
   isCompiledDistribution,
-  LEGACY_PACKAGE_NAME,
-  PACKAGE_NAME,
   packageRootDir,
 } from "./distribution.js";
 
 /**
  * Cross-copy markers: a user project with its own `@cursor/july` install
  * can load a second copy of this module in the same process; tsx and the
- * alias hooks must only be registered once.
+ * alias hooks must only be registered once. The key strings are shared with
+ * already-published copies; renaming them would double-register.
  */
 const TSX_REGISTERED_KEY = Symbol.for("cursor.agentkit.tsxRegistered");
 const ALIASES_REGISTERED_KEY = Symbol.for("cursor.agentkit.aliasesRegistered");
@@ -167,23 +164,9 @@ function registerFrameworkAliases(): void {
   if (markers[ALIASES_REGISTERED_KEY] === true) {
     return;
   }
-  const distDir = join(packageRootDir(), "dist");
-  const directAliases: Record<string, string> = {};
-  for (const [subpath, file] of AUTHORING_ENTRY_FILES) {
-    const target = pathToFileURL(join(distDir, file)).href;
-    const suffix = subpath === "" ? "" : `/${subpath}`;
-    // Always pin framework imports to this process's dist. Channel factories
-    // stash options in module-local WeakMaps; a second copy (tsx tsconfig
-    // paths → src/, or a mismatched node_modules install) makes
-    // getGitHubChannelOptions miss and hosted-delivery return 422.
-    directAliases[`${LEGACY_PACKAGE_NAME}${suffix}`] = target;
-    directAliases[`${PACKAGE_NAME}${suffix}`] = target;
-    directAliases[`${AGENTKIT_PACKAGE_NAME}${suffix}`] = target;
-  }
   const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
   const data: AuthoredAliasHookData = {
-    directAliases,
-    fallbackAliases: {},
+    directAliases: frameworkAliases(),
     // Hosted factory agents relative-import this package's src/ from a
     // monorepo checkout while npm install ran only in the agent directory.
     // Bare specifiers from that tree retry against this package.json.

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> {