@cursor/july 0.1.100 → 0.1.101

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

package/src/types.ts

@@ -50,6 +50,8 @@ export type DefinitionKind =
   | "instructions"
   | "tool"
   | "skill"
+  | "extension"
+  | "disabled-tool"
   | "connection"
   | "channel"
   | "http-channel"
@@ -952,6 +954,42 @@ export function normalizeConnectionEffects(
   return unique;
 }
 
+/**
+ * Trim, drop blanks, and unique-preserve authored
+ * {@link ConnectionConfig.tools} name lists. Invalid shapes are left
+ * for discovery.
+ */
+export function normalizeConnectionTools(tools: readonly string[]): string[] {
+  const unique: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of tools) {
+    const name = raw.trim();
+    if (name === "" || seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    unique.push(name);
+  }
+  return unique;
+}
+
+/** True when `toolName` passes the connection's `tools` / `disallowedTools` filter. */
+export function connectionAllowsTool(
+  filter: {
+    tools?: readonly string[];
+    disallowedTools?: readonly string[];
+  },
+  toolName: string
+): boolean {
+  if (filter.tools !== undefined && !filter.tools.includes(toolName)) {
+    return false;
+  }
+  return (
+    filter.disallowedTools === undefined ||
+    !filter.disallowedTools.includes(toolName)
+  );
+}
+
 /**
  * A tool's declared {@link ToolEffect} — fixed, or decided per call from
  * validated input for tools that read or write depending on their arguments
@@ -1065,6 +1103,66 @@ export interface SkillConfig {
 
 export type SkillDefinition = SkillConfig & BrandedDefinition<"skill">;
 
+// ============================================================================
+// Extensions (agent/extensions/<ns>.ts | agent/extensions/<ns>/extension.ts)
+// ============================================================================
+
+/**
+ * Input to `defineExtension`, the `extension.ts` at the root of an
+ * agent-shaped tree (`tools/`, `skills/`, `lib/`).
+ */
+export interface ExtensionOptions<TConfig, TInput = TConfig> {
+  /** The tree's directory; pass `import.meta.dirname`. */
+  root: string;
+  /** What the extension adds; shown by `info`. */
+  description?: string;
+  /** Mount configuration schema. A consumer's settings are validated at mount. */
+  config?: z.ZodType<TConfig, z.ZodTypeDef, TInput>;
+}
+
+/**
+ * What `extension.ts` default-exports. A consumer calls it from
+ * `agent/extensions/<ns>.ts` to mount the extension with a configuration;
+ * the extension's own modules import it to read that configuration.
+ */
+export interface Extension<TConfig = undefined, TInput = TConfig>
+  extends ExtensionDeclaration {
+  (
+    ...args: undefined extends TInput ? [config?: TInput] : [config: TInput]
+  ): ExtensionMount;
+  /** The mounted configuration (schema defaults applied); throws before the mount. */
+  readonly config: TConfig;
+}
+
+/** The mount-independent part of an {@link Extension}. */
+export interface ExtensionDeclaration {
+  readonly root: string;
+  readonly description: string | undefined;
+}
+
+/** What `agent/extensions/<ns>.ts` default-exports. */
+export interface ExtensionMount extends BrandedDefinition<"extension"> {
+  readonly extension: ExtensionDeclaration;
+  readonly config: unknown;
+}
+
+/**
+ * `export default disableTool()` in a directory mount's `tools/<name>.ts`
+ * removes the extension's `<ns>__<name>`.
+ */
+export type DisabledToolDefinition = BrandedDefinition<"disabled-tool">;
+
+/** One mounted extension and the names it contributed. */
+export interface DiscoveredExtension {
+  /** Mount namespace: the filename stem or directory name under `agent/extensions/`. */
+  name: string;
+  description?: string;
+  /** Composed tool names (`<ns>__<name>`), overrides applied. */
+  tools: string[];
+  /** Composed skill names (`<ns>__<name>`), overrides applied. */
+  skills: string[];
+}
+
 // ============================================================================
 // MCP connections (agent/mcp-connections/*.ts)
 // ============================================================================
@@ -1213,19 +1311,38 @@ export type InlineStdioConnectionConfig = {
  * cloud VM.
  */
 export type ConnectionConfig = (
-  | Exclude<ConnectionTransport, { cursorAccount: true }>
-  | {
-      cursorAccount: true;
+  | ((
+      | Exclude<ConnectionTransport, { cursorAccount: true }>
+      | {
+          cursorAccount: true;
+          /**
+           * Which account connectors to expose.
+           *
+           * - Omit, pass `"*"`, or pass `["*"]` to forward **every** connected
+           *   HTTP/SSE server on the account (no per-connector allowlist).
+           * - Pass connector names as they appear in the Cursor account's MCP
+           *   config (e.g. `["Linear", "Notion"]`) to restrict the set.
+           */
+          servers?: string[] | "*";
+        }
+    ) & {
       /**
-       * Which account connectors to expose.
+       * Tool-name allowlist. Same shape as {@link AgentConfig.tools}:
+       * when set, only these MCP tool names (the server's `tools/list`
+       * names) are advertised and callable through `host.mcp`. Names
+       * the server does not list are omitted, not guessed.
+       *
+       * A list of names is an allowlist. An object of handlers authors
+       * TypeScript tools ({@link InlineStdioConnectionConfig}).
        *
-       * - Omit, pass `"*"`, or pass `["*"]` to forward **every** connected
-       *   HTTP/SSE server on the account (no per-connector allowlist).
-       * - Pass connector names as they appear in the Cursor account's MCP
-       *   config (e.g. `["Linear", "Notion"]`) to restrict the set.
+       * On a model-visible connection this requires {@link advertiseTools}:
+       * an attached server would still expose every tool. On
+       * `host-connections/` it restricts `host.mcp` alone.
+       *
+       * Combines with {@link disallowedTools} as deny-wins.
        */
-      servers?: string[] | "*";
-    }
+      tools?: readonly string[];
+    })
   | InlineStdioConnectionConfig
 ) & {
   /** Documentation only; shown in `info` output. */
@@ -1300,6 +1417,16 @@ export type ConnectionConfig = (
    * are the same.
    */
   effects?: ConnectionEffects;
+  /**
+   * Tool-name denylist. Same shape as the Cursor SDK's
+   * `disallowedTools`: when set, these MCP tool names are omitted from
+   * the advertised set and rejected on `host.mcp`. Combines with
+   * {@link ConnectionConfig.tools} as deny-wins.
+   *
+   * On a model-visible connection this requires {@link advertiseTools}.
+   * On `host-connections/` it restricts `host.mcp` alone.
+   */
+  disallowedTools?: readonly string[];
 };
 
 /**
@@ -1322,7 +1449,11 @@ export function isInlineStdioConnection(
 ): connection is InlineStdioConnectionConfig & {
   description?: string;
 } {
-  return "tools" in connection && connection.tools !== undefined;
+  return (
+    "tools" in connection &&
+    connection.tools !== undefined &&
+    !Array.isArray(connection.tools)
+  );
 }
 
 /**
@@ -1873,9 +2004,13 @@ export interface SendMessageOptions {
   dryRun?: boolean;
   /**
    * ISO-8601 instant with a timezone, frozen at create: the prompt states
-   * it, {@link ToolContext.now} returns it, and tools that declare
-   * {@link ToolConfig.timeArgs} refuse calls not bounded at or before it. A
-   * tool that declares nothing still reads the present.
+   * it, {@link ToolContext.now} returns it, and every tool call is checked
+   * against it — a relative time argument (`now-1h`), an absolute one after
+   * the instant, or an omitted window a vendor schema declares is refused so
+   * the model retries with explicit absolute bounds. Tools may also declare
+   * {@link ToolConfig.timeArgs} for precise per-field checking. The check
+   * reads arguments, not behavior: a tool that reads present state without a
+   * time argument still answers from the present.
    */
   asOf?: string;
   /**
@@ -2791,6 +2926,8 @@ export interface DiscoveredTool {
   advertised?: true;
   /** Name of the advertising connection an advertised tool came from. */
   connection?: string;
+  /** Mounted extension this tool came from; absent for `agent/tools/`. */
+  extension?: string;
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.
@@ -2809,6 +2946,8 @@ export interface DiscoveredSkill {
   markdown: string;
   /** Package-relative sibling files. */
   files: Record<string, SkillFileSource>;
+  /** Mounted extension this skill came from; absent for `agent/skills/`. */
+  extension?: string;
 }
 
 export interface DiscoveredConnection {
@@ -2824,6 +2963,16 @@ export interface DiscoveredConnection {
    * Absent means every listed tool is advertised.
    */
   effects?: readonly ToolEffect[];
+  /**
+   * Normalized tool-name allowlist from {@link ConnectionConfig.tools}.
+   * Absent means every listed tool is kept.
+   */
+  tools?: readonly string[];
+  /**
+   * Normalized tool-name denylist from
+   * {@link ConnectionConfig.disallowedTools}.
+   */
+  disallowedTools?: readonly string[];
 }
 
 export interface DiscoveredChannel {
@@ -2895,6 +3044,11 @@ export interface ResolvedAgent {
   architecture?: AgentArchitecture;
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
+  /**
+   * Mounted `agent/extensions/`. Their tools and skills are already merged
+   * into {@link tools} and {@link skills}; this records provenance.
+   */
+  extensions?: DiscoveredExtension[];
   connections: DiscoveredConnection[];
   /**
    * MCP connections from `agent/host-connections/`. Host tools and
@@ -2977,11 +3131,15 @@ export interface AgentProjectInfo {
     inputSchema: JsonSchemaObject;
   }>;
   skills: Array<{ name: string; description: string }>;
+  /** Mounted extensions and the tool / skill names each contributed. */
+  extensions: DiscoveredExtension[];
   connections: Array<{
     name: string;
     transport: string;
     advertiseTools?: boolean;
     effects?: readonly ToolEffect[];
+    tools?: readonly string[];
+    disallowedTools?: readonly string[];
     /**
      * Present only for `cursorAccount` connections: the connector-name
      * allowlist, or `"*"` for every connected server. Structured twin of the