@cursor/july 0.1.99 → 0.1.101

package/src/internal/start-log-store.ts

@@ -0,0 +1,177 @@
+/**
+ * Durable hosted `start.log` on the framework file store. **v2 only.**
+ *
+ * The engine tees stdout/stderr to a local file. That file is the v2
+ * customer log (errors, traces, debug). It is NOT written to S3 per line:
+ * callers snapshot the local buffer and PUT once. The Temporal host does
+ * a last catch-up at the end of the delivery so the object is complete
+ * after park/discard.
+ *
+ * Same flush moments as `hosted-execution.json` and session-runs —
+ * see `hosted-execution-flush.ts`. Keys: {@link storageKeys.log}.
+ * Values are raw UTF-8, not JSON.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { FileSink } from "../files.js";
+import {
+  cursorFrameworkStoreSourceId,
+  cursorHostedFiles,
+} from "../files-backends/cursor-hosted.js";
+import { storageKeys } from "../storage-protocol.js";
+import type { AgentProject } from "../types.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { describeError } from "./describe-error.js";
+
+/**
+ * Last N bytes flushed to the store. Matches the Temporal catch-up cap
+ * so guest snapshots and host catch-up stay interchangeable. The store
+ * allows 64 MiB; this keeps the dashboard snapshot bounded.
+ */
+export const START_LOG_STORE_MAX_BYTES: number = 2 * 1024 * 1024;
+
+/** Same path the hosted start command tees. Overridable in tests. */
+export const DEFAULT_ENGINE_START_LOG_PATH =
+  "/workspace/.agent-serve/start.log";
+
+export interface StartLogStore {
+  persist(startLogId: string, contents: string): Promise<void>;
+  read(startLogId: string): Promise<string | undefined>;
+}
+
+function decodeSinkBody(body: Uint8Array | { body: Uint8Array }): Uint8Array {
+  return body instanceof Uint8Array ? body : body.body;
+}
+
+export function tailStartLogText(raw: string, maxBytes: number): string {
+  const encoded = new TextEncoder().encode(raw);
+  if (encoded.byteLength <= maxBytes) {
+    return raw;
+  }
+  return new TextDecoder().decode(
+    encoded.subarray(encoded.byteLength - maxBytes)
+  );
+}
+
+export function resolveEngineStartLogPath(
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const configured = env.AGENT_SERVE_ENGINE_START_LOG_PATH?.trim();
+  return configured !== undefined && configured.length > 0
+    ? configured
+    : DEFAULT_ENGINE_START_LOG_PATH;
+}
+
+/**
+ * Read the local engine tee. Missing/empty is `undefined` (no store write).
+ * Soft-fail: a local read error must not change hosted-execution HTTP.
+ */
+export async function readLocalStartLogText(args?: {
+  path?: string;
+  maxBytes?: number;
+}): Promise<string | undefined> {
+  const path = args?.path ?? resolveEngineStartLogPath();
+  const maxBytes = args?.maxBytes ?? START_LOG_STORE_MAX_BYTES;
+  try {
+    const raw = await readFile(path, "utf8");
+    if (raw.length === 0) {
+      return undefined;
+    }
+    return tailStartLogText(raw, maxBytes);
+  } catch (error) {
+    if (
+      error !== null &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code?: string }).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    return undefined;
+  }
+}
+
+export function createStartLogStore(input: {
+  sink: FileSink;
+  agentName: string;
+  logger?: (line: string) => void;
+}): StartLogStore {
+  const { sink, agentName } = input;
+  const logger = input.logger ?? (() => {});
+
+  return {
+    async persist(startLogId, contents) {
+      const key = storageKeys.log(agentName, startLogId);
+      const body = tailStartLogText(contents, START_LOG_STORE_MAX_BYTES);
+      try {
+        await sink.put(key, new TextEncoder().encode(body));
+      } catch (error) {
+        logger(
+          `[agent-sdk] start-log: persist failed for ${startLogId} (${describeError(error)})`
+        );
+      }
+    },
+
+    async read(startLogId) {
+      const key = storageKeys.log(agentName, startLogId);
+      try {
+        const body = await sink.get(key);
+        if (body === undefined) {
+          return undefined;
+        }
+        const text = new TextDecoder().decode(decodeSinkBody(body));
+        return text.length === 0 ? undefined : text;
+      } catch (error) {
+        logger(
+          `[agent-sdk] start-log: read failed for ${startLogId} (${describeError(error)})`
+        );
+        return undefined;
+      }
+    },
+  };
+}
+
+/**
+ * Same selection as the session-run log: architecture-v2 hosted engines.
+ */
+export function selectStartLogStore(input: {
+  project: AgentProject;
+  logger?: (line: string) => void;
+  env?: Record<string, string | undefined>;
+}): StartLogStore | undefined {
+  if (input.project.agent.architecture !== "v2") {
+    return undefined;
+  }
+  const env = input.env ?? process.env;
+  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+    return undefined;
+  }
+  const envSnapshot = env as NodeJS.ProcessEnv;
+  return createStartLogStore({
+    sink: cursorHostedFiles({
+      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveApiKey: () => resolveApiKeySync()?.apiKey,
+    }),
+    agentName: input.project.name,
+    logger: input.logger,
+  });
+}
+
+/**
+ * Snapshot the local tee into the store. No-op when the file is missing
+ * or empty. Soft-fail inside {@link StartLogStore.persist}.
+ */
+export async function flushLocalStartLog(args: {
+  store: StartLogStore;
+  startLogId: string;
+  path?: string;
+}): Promise<void> {
+  const contents = await readLocalStartLogText(
+    args.path === undefined ? undefined : { path: args.path }
+  );
+  if (contents === undefined) {
+    return;
+  }
+  await args.store.persist(args.startLogId, contents);
+}

package/src/internal/storage-coordinator.ts

@@ -38,7 +38,6 @@ import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
 import type { EvalRunStorage } from "./eval-run-store.js";
-import { isAuthorKvUnsupported } from "./null-kv-storage.js";
 import type {
   AuthorKvStore,
   EvalAbStore,
@@ -469,18 +468,9 @@ export class StorageCoordinator
   /**
    * Whether the sink can serve awaited author reads/writes (`get` is
    * required — `put` is always present on {@link StorageConfig}).
-   *
-   * A sink may keep `get` for framework session state while refusing author
-   * KV: hosted v2 reads sessions from the framework file store but has no
-   * working KV backend, and author handlers that cannot read their own
-   * writes back are better served by the local-disk fallback than by a sink
-   * that accepts every write and forgets it.
    */
   get supportsAuthorKv(): boolean {
-    return (
-      this.definition.get !== undefined &&
-      !isAuthorKvUnsupported(this.definition)
-    );
+    return this.definition.get !== undefined;
   }
 
   /**

package/src/internal/tool-policy.ts

@@ -16,7 +16,11 @@ import type {
   ToolEffectDeclaration,
   ToolExecuteResult,
 } from "../types.js";
-import { timeArgViolation } from "./as-of.js";
+import {
+  forwardTimeArgument,
+  missingTimeWindow,
+  timeArgViolation,
+} from "./as-of.js";
 
 /** What the host does with one tool call. */
 export type ToolDecision =
@@ -64,6 +68,14 @@ export interface ToolCallFacts {
   asOf?: string;
   /** The tool's declared time-bound argument names, if it made them. */
   timeArgs?: readonly string[];
+  /**
+   * String-typed time-window property names a vendor tool's own input schema
+   * declares (`from`/`to`/`since`/...). In a frozen session a call that omits
+   * one is refused: the vendor fills an omitted window with a live default
+   * the argument walker can never see. Advertised/bridged MCP tools only —
+   * authored tools declare {@link timeArgs} instead.
+   */
+  timeWindow?: readonly string[];
 }
 
 /**
@@ -159,14 +171,32 @@ function unclassifiedRefusal(toolName: string): string {
 export function decideToolCall(facts: ToolCallFacts): ToolDecision {
   // Before the dry-run split: a frozen session bounds its reads whether or
   // not its writes are stubbed.
-  if (
-    facts.asOf !== undefined &&
-    facts.timeArgs !== undefined &&
-    facts.timeArgs.length > 0
-  ) {
-    const violation = timeArgViolation(facts.input, facts.timeArgs, facts.asOf);
-    if (violation !== undefined) {
-      return { kind: "unbounded", message: violation };
+  if (facts.asOf !== undefined) {
+    if (facts.timeArgs !== undefined && facts.timeArgs.length > 0) {
+      const violation = timeArgViolation(
+        facts.input,
+        facts.timeArgs,
+        facts.asOf
+      );
+      if (violation !== undefined) {
+        return { kind: "unbounded", message: violation };
+      }
+    }
+    const forward = forwardTimeArgument(facts.input, facts.asOf);
+    if (forward !== undefined) {
+      return { kind: "unbounded", message: forward };
+    }
+    // Present values are checked above; absent ones are the vendor's live
+    // default window, which no walker can see. Require them explicitly.
+    if (facts.timeWindow !== undefined) {
+      const omitted = missingTimeWindow(
+        facts.input,
+        facts.timeWindow,
+        facts.asOf
+      );
+      if (omitted !== undefined) {
+        return { kind: "unbounded", message: omitted };
+      }
     }
   }
   if (!facts.dryRun) {

package/src/storage-backends/cursor-hosted-v2.ts

@@ -0,0 +1,219 @@
+/**
+ * Cursor-managed durable KV for hosted **architecture v2** agents.
+ *
+ * Talks to the AgentSDK v2 KV proxy
+ * (`POST /internal/agentsdk/kv/*`) using the engine's pod
+ * `CURSOR_API_KEY`. The server resolves the v2 deployment from that service
+ * account (factorydb `agentsdk_deployment`) and persists rows in factorydb
+ * `agentsdk_kv` — v1's Bugbot-backed `/internal/agent-serve/storage/*`
+ * routes cannot resolve a v2 pod credential at all.
+ *
+ * The v2 wire protocol is four routes, not v1's eight:
+ *
+ * - `POST /internal/agentsdk/kv/get`
+ *   `{ key }` → `{ found, value, version }` — reads always carry the CAS
+ *   version token ({@link KvV2GetResponse}).
+ * - `POST /internal/agentsdk/kv/put`
+ *   `{ key, value, ifAbsent? | ifVersion? }` → `{ ok, version, current }`
+ *   ({@link KvV2PutResponse}) — one write primitive: last-write-wins when
+ *   unconditional (still bumps the token), atomic create-if-absent with
+ *   `ifAbsent: true`, atomic compare-and-swap with `ifVersion`.
+ * - `POST /internal/agentsdk/kv/delete` `{ key }` → `{ ok }`.
+ * - `POST /internal/agentsdk/kv/list`
+ *   `{ prefix, limit?, cursor?, keysOnly? }` → `{ entries, nextCursor }`
+ *   ({@link KvV2ListResponse}) — ascending key order with keyset
+ *   pagination. `list` / `listKeys` below drain every page, so the v1
+ *   truncated-scan failure mode does not exist here.
+ *
+ * Eval runs and A/B samples still ride the v1 storage proxy's dedicated
+ * tables (`evals` / `abs` below); moving them to factorydb is a separate
+ * follow-up from the KV cutover.
+ *
+ * This backend is platform-selected for architecture v2
+ * (framework-storage-selection.ts) — authors never import it; `agent/storage.ts`
+ * is rejected on v2.
+ */
+
+import type {
+  StorageABTable,
+  StorageCasTable,
+  StorageConfig,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
+import {
+  CURSOR_HOSTED_STORAGE,
+  type CursorHostedStorageOptions,
+  cursorHostedStorage,
+  storageRpc,
+} from "./cursor-hosted.js";
+
+const KV_V2_PREFIX = "/internal/agentsdk/kv";
+
+/** Wire shape of the v2 `get` route. `null` ⇒ JSON `undefined`. */
+export interface KvV2GetResponse {
+  found: boolean;
+  value: JsonValue | null;
+  version: string | null;
+}
+
+/** Wire shape of the v2 `put` route (all three write modes). */
+export interface KvV2PutResponse {
+  ok: boolean;
+  /** New version token on an accepted write, else `null`. */
+  version: string | null;
+  /** Entry observed when a conditional write lost; `null` when absent. */
+  current: { value: JsonValue | null; version: string } | null;
+}
+
+/** Wire shape of the v2 `list` route. */
+export interface KvV2ListResponse {
+  entries: Array<{
+    key: string;
+    /** Omitted when the request asked for keys only. */
+    value?: JsonValue | null;
+    version: string;
+  }>;
+  /** Last key of this page when more rows remain, else `null`. */
+  nextCursor: string | null;
+}
+
+type CursorHostedStorageV2Methods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  readonly [CURSOR_HOSTED_STORAGE]: true;
+  cas: StorageCasTable;
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+function toCasResult(response: KvV2PutResponse): KvCasResult {
+  if (response.ok) {
+    if (response.version === null) {
+      throw new Error(
+        "cursorHostedStorageV2: conditional write succeeded without a version token"
+      );
+    }
+    return { ok: true, version: response.version };
+  }
+  const current: KvVersionedEntry | undefined =
+    response.current === null
+      ? undefined
+      : {
+          value: response.current.value ?? null,
+          version: response.current.version,
+        };
+  return { ok: false, current };
+}
+
+/**
+ * Drain every page of a v2 `list` scan. The server pages by keyset (each
+ * `nextCursor` is the strictly-greatest key returned so far), so a cursor
+ * that fails to advance means a broken server — fail loudly rather than
+ * loop forever.
+ */
+async function listAllPages(
+  options: CursorHostedStorageOptions,
+  body: { prefix: string; keysOnly?: boolean }
+): Promise<KvV2ListResponse["entries"]> {
+  const entries: KvV2ListResponse["entries"] = [];
+  let cursor: string | undefined;
+  for (;;) {
+    const page = await storageRpc<KvV2ListResponse>(
+      options,
+      `${KV_V2_PREFIX}/list`,
+      cursor === undefined ? body : { ...body, cursor }
+    );
+    entries.push(...page.entries);
+    if (page.nextCursor === null) {
+      return entries;
+    }
+    if (cursor !== undefined && page.nextCursor <= cursor) {
+      throw new Error(
+        `cursorHostedStorageV2: list("${body.prefix}") cursor did not advance`
+      );
+    }
+    cursor = page.nextCursor;
+  }
+}
+
+/**
+ * Architecture-v2 `defineStorage` methods (AgentSDK v2 KV proxy → factorydb
+ * `agentsdk_kv`). Platform-selected; spread into `defineStorage({...})` by
+ * framework-storage-selection.ts. No `listNewest`: v2 session records live
+ * on the framework file store, so the only consumer of write-time ordering
+ * never reaches this backend and the engine's `list` fallback covers the
+ * rest.
+ */
+export function cursorHostedStorageV2(
+  options: CursorHostedStorageOptions = {}
+): CursorHostedStorageV2Methods {
+  // Eval runs and A/B samples stay on the v1 proxy's dedicated tables.
+  const v1 = cursorHostedStorage(options);
+  return {
+    [CURSOR_HOSTED_STORAGE]: true,
+    async put(key, value): Promise<void> {
+      await storageRpc(options, `${KV_V2_PREFIX}/put`, { key, value });
+    },
+    async get(key): Promise<JsonValue | undefined> {
+      const result = await storageRpc<KvV2GetResponse>(
+        options,
+        `${KV_V2_PREFIX}/get`,
+        { key }
+      );
+      if (!result.found) {
+        return undefined;
+      }
+      return result.value ?? undefined;
+    },
+    async delete(key): Promise<void> {
+      await storageRpc(options, `${KV_V2_PREFIX}/delete`, { key });
+    },
+    async list(prefix): Promise<StorageEntry[]> {
+      const entries = await listAllPages(options, { prefix });
+      return entries.map((entry) => ({
+        key: entry.key,
+        value: entry.value ?? null,
+      }));
+    },
+    cas: {
+      async getWithVersion(key): Promise<KvVersionedEntry | undefined> {
+        const result = await storageRpc<KvV2GetResponse>(
+          options,
+          `${KV_V2_PREFIX}/get`,
+          { key }
+        );
+        if (!result.found || result.version === null) {
+          return undefined;
+        }
+        return { value: result.value ?? null, version: result.version };
+      },
+      async putIfAbsent(key, value): Promise<KvCasResult> {
+        const result = await storageRpc<KvV2PutResponse>(
+          options,
+          `${KV_V2_PREFIX}/put`,
+          { key, value, ifAbsent: true }
+        );
+        return toCasResult(result);
+      },
+      async putIfVersion(key, value, expectedVersion): Promise<KvCasResult> {
+        const result = await storageRpc<KvV2PutResponse>(
+          options,
+          `${KV_V2_PREFIX}/put`,
+          { key, value, ifVersion: expectedVersion }
+        );
+        return toCasResult(result);
+      },
+      async listKeys(prefix): Promise<string[]> {
+        const entries = await listAllPages(options, {
+          prefix,
+          keysOnly: true,
+        });
+        return entries.map((entry) => entry.key);
+      },
+    },
+    evals: v1.evals,
+    abs: v1.abs,
+  };
+}

package/src/storage-backends/cursor-hosted.ts

@@ -207,7 +207,12 @@ function resolveBaseUrl(options: CursorHostedStorageOptions): string {
   return raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
 
-async function storageRpc<T>(
+/**
+ * One authenticated POST to the control-plane proxy. Shared with the
+ * architecture-v2 backend (`cursor-hosted-v2.ts`), which speaks a different
+ * route family over the same transport and credential chain.
+ */
+export async function storageRpc<T>(
   options: CursorHostedStorageOptions,
   path: string,
   body: Record<string, unknown>

package/src/storage-protocol.ts

@@ -39,6 +39,7 @@ const DURABLE_SESSION_RECORD_KEY_RE =
  * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
+ * | `agentkit/v1/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
  *
@@ -69,6 +70,17 @@ export const storageKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
   sessionRunsPrefix: (agent: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/session-runs/`,
+  /**
+   * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
+   * `logId` is the factory `ses_…` after a `send`, or
+   * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
+   * before a session exists. Skip/task admissions do not write this key.
+   * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
+   * objects, and this key is flushed in snapshots, not per line.
+   */
+  log: (agent: string, logId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/logs/${keySegment(logId)}`,
+  logsPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/logs/`,
   continuation: (
     agent: string,
     channelId: string,
@@ -111,6 +123,31 @@ export const storageKeys = {
  */
 export const MAX_KEY_SEGMENT_BYTES = 256;
 
+/**
+ * Stable start-log object id. A `send` attaches to the factory session
+ * so the factory/dashboard session-runs read can see it. Admission that
+ * fails before a session exists is keyed on the Temporal workflow run
+ * (`wf:{workflowId}` or `wf:{workflowId}/{runId}`) so the object joins
+ * the Temporal UI. A successful skip/task writes nothing — there is no
+ * customer log.
+ */
+export function frameworkStartLogId(args: {
+  sessionPublicId?: string | null;
+  workflowId?: string | null;
+  runId?: string | null;
+}): string | undefined {
+  const sessionPublicId = args.sessionPublicId?.trim() ?? "";
+  if (sessionPublicId.length > 0) {
+    return sessionPublicId;
+  }
+  const workflowId = args.workflowId?.trim() ?? "";
+  if (workflowId.length === 0) {
+    return undefined;
+  }
+  const runId = args.runId?.trim() ?? "";
+  return runId.length > 0 ? `wf:${workflowId}/${runId}` : `wf:${workflowId}`;
+}
+
 /**
  * URI-encode one caller-controlled key segment, substituting a `sha256:…`
  * digest of the raw value when the encoding exceeds

package/src/storage.ts

@@ -63,6 +63,7 @@ export type {
   DurableSessionSummary,
 } from "./storage-protocol.js";
 export {
+  frameworkStartLogId,
   GOLDEN_DURABLE_SESSION_RECORD,
   isDurableSessionRecordKey,
   keySegment,