@cursor/july 0.1.102 → 0.1.103

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