@cursor/july 0.1.96 → 0.1.99

package/src/internal/storage-coordinator.ts

@@ -30,6 +30,7 @@ import {
   resolveStoragePolicy,
   type StorageContext,
   type StorageDefinition,
+  type StorageEntry,
   storageKeys,
 } from "../storage.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
@@ -37,6 +38,7 @@ 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,
@@ -97,6 +99,18 @@ interface SessionBuffer {
   debounceTimer?: ReturnType<typeof setTimeout>;
 }
 
+/** Session records out of raw sink entries; rows without a usable id are dropped. */
+function sessionRecordsOf(entries: readonly StorageEntry[]): SessionRecord[] {
+  return entries
+    .map((entry) => entry.value as unknown as SessionRecord)
+    .filter(
+      (record) =>
+        record != null &&
+        typeof record.sessionId === "string" &&
+        record.sessionId !== ""
+    );
+}
+
 export class StorageCoordinator
   implements FrameworkSessionStore, AuthorKvStore, EvalAbStore
 {
@@ -315,14 +329,31 @@ export class StorageCoordinator
     if (!Array.isArray(entries)) {
       throw new Error("storage list returned a non-array");
     }
-    return entries
-      .map((entry) => entry.value as unknown as SessionRecord)
-      .filter(
-        (record) =>
-          record != null &&
-          typeof record.sessionId === "string" &&
-          record.sessionId !== ""
-      );
+    return sessionRecordsOf(entries);
+  }
+
+  /**
+   * Newest-written session records from the sink (`GET /v1/sessions?latest=1`
+   * on a host whose local store has nothing for the caller). Same error
+   * posture as {@link listSessionsFromSink}; `undefined` when the sink
+   * cannot order by write time, so the caller falls back to the full list.
+   */
+  async listNewestSessionsFromSink(
+    limit: number
+  ): Promise<SessionRecord[] | undefined> {
+    const listNewest = this.definition.listNewest;
+    if (listNewest === undefined) {
+      return undefined;
+    }
+    const entries = await listNewest(
+      storageKeys.sessionPrefix(this.agentName),
+      limit,
+      this.context("restore")
+    );
+    if (!Array.isArray(entries)) {
+      throw new Error("storage listNewest returned a non-array");
+    }
+    return sessionRecordsOf(entries);
   }
 
   /**
@@ -438,9 +469,18 @@ 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;
+    return (
+      this.definition.get !== undefined &&
+      !isAuthorKvUnsupported(this.definition)
+    );
   }
 
   /**

package/src/internal/storage-roles.ts

@@ -54,6 +54,13 @@ export interface FrameworkSessionStore {
 
   listSessions(): Promise<SessionRecord[]>;
   listSessionsFromSink(): Promise<SessionRecord[]>;
+  /**
+   * The `limit` most recently written session records from the sink,
+   * newest first; `undefined` when the sink has no `listNewest`.
+   */
+  listNewestSessionsFromSink(
+    limit: number
+  ): Promise<SessionRecord[] | undefined>;
   listSessionEvents(sessionId: string): Promise<SessionEvent[]>;
   getSessionById(sessionId: string): Promise<SessionRecord | undefined>;
   getSessionByContinuation(

package/src/internal/stream-progress.ts

@@ -154,6 +154,25 @@ export function createStreamProgress(options?: {
           );
           break;
         }
+        case "action.auth_requested": {
+          closeAssistant();
+          write(
+            `    ${c.yellow("⏸")} ${c.bold(event.data.connection)} ${c.dim(
+              "awaiting MCP authorization"
+            )}\n`
+          );
+          break;
+        }
+        case "action.auth_resolved": {
+          const mark =
+            event.data.decision === "approve" ? c.green("✓") : c.red("✗");
+          write(
+            `    ${mark} ${c.bold(event.data.connection)} ${c.dim(
+              event.data.decision === "approve" ? "connected" : "denied"
+            )}\n`
+          );
+          break;
+        }
         case "action.result": {
           if (
             event.data.toolName === "task" &&

package/src/internal/tool-policy.ts

@@ -10,11 +10,13 @@
  */
 
 import type {
+  DiscoveredTool,
   McpToolAnnotations,
   ToolEffect,
   ToolEffectDeclaration,
   ToolExecuteResult,
 } from "../types.js";
+import { timeArgViolation } from "./as-of.js";
 
 /** What the host does with one tool call. */
 export type ToolDecision =
@@ -23,12 +25,17 @@ export type ToolDecision =
   /** Do not run it; return this to the model instead. */
   | { kind: "answer"; result: ToolExecuteResult }
   /**
-   * Do not run it; fail the call with this message. Only ever produced in a
-   * dry run, for an MCP tool nothing classifies: stubbing it would let the
-   * run reach a confident conclusion from no data, and running it could leak
-   * a real write — refusing is the one failure that is loud.
+   * Do not run it; fail the call with this message. Only produced in a dry
+   * run, for an MCP tool nothing classifies: stubbing it would let the run
+   * reach a confident conclusion from no data, and running it could leak a
+   * real write — refusing is the one failure that is loud.
    */
-  | { kind: "refuse"; message: string };
+  | { kind: "refuse"; message: string }
+  /**
+   * Do not run it; the `asOf` session was asked to read without absolute
+   * bounds, which would read the present.
+   */
+  | { kind: "unbounded"; message: string };
 
 /** What a policy decision needs to know about the call. */
 export interface ToolCallFacts {
@@ -47,12 +54,16 @@ export interface ToolCallFacts {
   /** What a stubbed write should answer with, if the tool supplied one. */
   dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
   /**
-   * Validated input, as the tool body would receive it. Only read by a
-   * per-call `effect` predicate and by a `dryRunResult` function, so a caller
-   * with neither — a bridged MCP tool, which carries no declaration at all —
-   * can omit it.
+   * Validated input, as the tool body would receive it. Read by a per-call
+   * `effect` predicate, a `dryRunResult` function, and the {@link timeArgs}
+   * bound check, so a caller with none of those — a bridged MCP tool, which
+   * carries no declaration at all — can omit it.
    */
   input?: unknown;
+  /** The session's frozen instant, when it has one. */
+  asOf?: string;
+  /** The tool's declared time-bound argument names, if it made them. */
+  timeArgs?: readonly string[];
 }
 
 /**
@@ -111,6 +122,23 @@ export function classifyAnnotationsEffect(
   return undefined;
 }
 
+/**
+ * The effect of one direct call on a discovered tool, the same way
+ * {@link decideToolCall} reads it: the authored declaration when there is
+ * one (possibly per input), else the MCP server's own annotations for an
+ * advertised passthrough. `undefined` is an advertised tool nothing
+ * classifies; callers gating on "read" treat it as a write.
+ */
+export function directCallEffect(
+  tool: Pick<DiscoveredTool, "advertised" | "annotations" | "definition">,
+  input: unknown
+): ToolEffect | undefined {
+  if (tool.definition.effect === undefined && tool.advertised === true) {
+    return classifyAnnotationsEffect(tool.annotations);
+  }
+  return resolveEffect(tool.definition.effect, input);
+}
+
 /**
  * What a dry run answers when nothing classifies an MCP tool. Deliberately
  * reads as a strict API rather than disclosing the session's posture (see
@@ -129,6 +157,18 @@ function unclassifiedRefusal(toolName: string): string {
 
 /** Decide what to do with one tool call. Pure; no I/O, no session state. */
 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.dryRun) {
     return { kind: "run" };
   }

package/src/internal/trajectory.ts

@@ -170,6 +170,16 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
         }
         break;
       }
+      case "action.auth_requested": {
+        break;
+      }
+      case "action.auth_resolved": {
+        const pending = pendingCalls.get(event.data.callId);
+        if (pending !== undefined) {
+          pending.approvalDecision = event.data.decision;
+        }
+        break;
+      }
       case "action.result": {
         const pending = pendingCalls.get(event.data.callId);
         if (pending !== undefined) {

package/src/internal/turn-outbox.ts

@@ -0,0 +1,85 @@
+/**
+ * Hand-off of a message to the server that holds the session's turn lease.
+ *
+ * Blue/green replicas share a state root but not a process, and only the
+ * lease holder can admit a message to its running turn. A server that
+ * receives a message for a turn it does not own drops it here, under
+ * `<stateRoot>/outbox/<sessionId>`; the holder takes everything out while its
+ * turn runs and once more after releasing the lease. Local messages never
+ * touch this.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+
+export interface OutboxItem<T> {
+  message: string;
+  options: T;
+}
+
+function safeKey(sessionId: string): string {
+  const sanitized = sessionId
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^\.+/, "")
+    .replace(/\.+/g, "_")
+    .slice(0, 180);
+  return sanitized === "" ? "_empty" : sanitized;
+}
+
+export class TurnOutbox<T> {
+  private readonly rootDir: string;
+
+  constructor(rootDir: string) {
+    this.rootDir = rootDir;
+  }
+
+  private dir(sessionId: string): string {
+    return join(this.rootDir, safeKey(sessionId));
+  }
+
+  async post(sessionId: string, item: OutboxItem<T>): Promise<void> {
+    const dir = this.dir(sessionId);
+    await mkdir(dir, { recursive: true });
+    // Timestamp first so a listing sorts in arrival order.
+    const path = join(dir, `${Date.now()}-${randomUUID()}.json`);
+    await writeFile(`${path}.tmp`, `${JSON.stringify(item)}\n`, "utf8");
+    await rename(`${path}.tmp`, path);
+  }
+
+  /** Remove and return everything posted, in arrival order. */
+  async takeAll(sessionId: string): Promise<OutboxItem<T>[]> {
+    const dir = this.dir(sessionId);
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch {
+      return [];
+    }
+    const items: OutboxItem<T>[] = [];
+    for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+      const path = join(dir, name);
+      try {
+        const raw = await readFile(path, "utf8");
+        await unlink(path);
+        items.push(JSON.parse(raw) as OutboxItem<T>);
+      } catch {
+        // Taken by the holder between readdir and here.
+      }
+    }
+    return items;
+  }
+
+  async clear(sessionId: string): Promise<void> {
+    await rm(this.dir(sessionId), { recursive: true, force: true });
+  }
+}

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

@@ -108,7 +108,7 @@ export function isCursorHostedStorage(value: unknown): boolean {
 }
 
 type CursorHostedStorageMethods = Required<
-  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+  Pick<StorageConfig, "put" | "get" | "delete" | "list" | "listNewest">
 > & {
   readonly [CURSOR_HOSTED_STORAGE]: true;
   cas: StorageCasTable;
@@ -284,6 +284,18 @@ export function cursorHostedStorage(
       }>(options, "/internal/agent-serve/storage/kv/list", { prefix });
       return result.entries;
     },
+    async listNewest(prefix, limit): Promise<StorageEntry[]> {
+      // Same route; the server orders the prefix range by row write time
+      // and caps the rows instead of returning the whole range.
+      const result = await storageRpc<{
+        entries: Array<{ key: string; value: JsonValue }>;
+      }>(options, "/internal/agent-serve/storage/kv/list", {
+        prefix,
+        limit,
+        newestFirst: true,
+      });
+      return result.entries;
+    },
     // Conditional writes over the same proxy (server routes: see the CAS
     // wire-protocol block above). The proxy scopes rows from the service
     // account, so ctx is not part of the wire contract.

package/src/storage-protocol.ts

@@ -38,6 +38,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}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
  *
@@ -59,6 +60,15 @@ export const storageKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
   sessionEventsPrefix: (agent: string, sessionId: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
+  /**
+   * One session-level hosted-execution log (v2 only). `sessionPublicId` is
+   * the factory `ses_…` so a throw that never minted a July session still
+   * lands under a stable key. Per-execution rows live inside the document.
+   */
+  sessionRun: (agent: string, sessionPublicId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
+  sessionRunsPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-runs/`,
   continuation: (
     agent: string,
     channelId: string,

package/src/storage.ts

@@ -275,6 +275,18 @@ export interface StorageConfig {
     prefix: string,
     ctx: StorageContext
   ): StorageEntry[] | Promise<StorageEntry[]>;
+  /**
+   * The `limit` most recently **written** entries under a prefix, newest
+   * first. Optional — a backend-native shortcut for `GET /v1/sessions?latest=1`
+   * on a replacement host, where the alternative is listing every session
+   * row. Without it the engine falls back to `list`. Write order is an
+   * approximation of the records' own `updatedAt`; callers tolerate that.
+   */
+  listNewest?(
+    prefix: string,
+    limit: number,
+    ctx: StorageContext
+  ): StorageEntry[] | Promise<StorageEntry[]>;
 }
 
 export type StorageDefinition = StorageConfig & {

package/src/tools.ts

@@ -99,6 +99,15 @@ type ServerToolConfig<TSchema> = {
    * write, so a dry-run session answers it instead of running it.
    */
   effect?: ToolEffectDeclaration<ToolInput<TSchema>>;
+  /**
+   * Input properties carrying time bounds. In an `asOf` session each named
+   * argument must be an absolute ISO-8601 instant with a timezone, no later
+   * than the frozen instant; a call that omits one, or supplies a relative
+   * or later value, is refused so the model retries with absolute bounds.
+   * Names must exist in {@link inputSchema} or the frozen session refuses to
+   * start. Ignored without `asOf`.
+   */
+  timeArgs?: readonly string[];
   /** What a `"write"` tool returns in a dry-run session. */
   dryRunResult?:
     | ToolExecuteResult
@@ -126,10 +135,11 @@ type AgentToolConfig<TSchema> = {
   needsApproval?: never;
   /**
    * Agent tools run inside the harness, not through the host's tool path, so
-   * a dry run cannot answer them. Classify the work as a server tool if it
-   * needs to be dry-runnable.
+   * a dry run cannot answer them and an `asOf` session cannot bound them.
+   * Classify the work as a server tool if it needs either.
    */
   effect?: never;
+  timeArgs?: never;
   dryRunResult?: never;
 };
 

package/src/types.ts

@@ -316,7 +316,8 @@ export interface AgentConcurrencyOptions {
    * {@link MAX_RUNNING_TURNS_LIMIT}. Omit for unlimited.
    *
    * A queued turn still counts as `running` for busy semantics
-   * (follow-ups preempt it; direct tool calls get `SessionBusyError`),
+   * (follow-ups preempt it; direct write-effect tool calls get
+   * `SessionBusyError`),
    * and a follow-up that preempts a queued turn re-queues at the back.
    */
   maxRunningTurns?: number;
@@ -879,6 +880,8 @@ export interface ToolContext {
    * `subagent.completed`). Omitted for scratch `callTool` with no session.
    */
   emit?: (payload: SessionEventPayload) => void;
+  /** The session's frozen `asOf`, or the wall clock. Use instead of `Date.now()`. */
+  now(): Date;
 }
 
 /**
@@ -991,6 +994,17 @@ export interface ToolConfig<TInput> {
    * write, so a dry run stubs it — see {@link ToolEffect}.
    */
   effect?: ToolEffectDeclaration<TInput>;
+  /**
+   * Input properties that carry time bounds. In a session created with
+   * {@link SendMessageOptions.asOf}, every named argument must be an
+   * absolute ISO-8601 instant with a timezone, no later than the session's
+   * frozen instant — a call that omits one, or supplies a relative or later
+   * value, is refused so the model retries with absolute bounds. Names must
+   * exist in {@link inputSchema}; a session with `asOf` refuses to start
+   * otherwise, because a misspelled name would silently check nothing.
+   * Ignored in sessions without `asOf`.
+   */
+  timeArgs?: readonly string[];
   /**
    * What a write tool returns in a dry-run session instead of executing.
    *
@@ -1024,6 +1038,7 @@ export interface ToolDefinition extends BrandedDefinition<"tool"> {
   readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly needsApproval?: ToolNeedsApproval<never>;
   readonly effect?: ToolEffectDeclaration<never>;
+  readonly timeArgs?: readonly string[];
   readonly dryRunResult?:
     | ToolExecuteResult
     | ((input: never) => ToolExecuteResult);
@@ -1151,7 +1166,9 @@ export function cursorAccountServersHasMixedWildcard(
  */
 export function isHostOauthConnectionTransport(
   transport: ConnectionTransport
-): boolean {
+): transport is Extract<ConnectionTransport, { url: string }> & {
+  oauth: true;
+} {
   return "url" in transport && transport.oauth === true;
 }
 
@@ -1380,8 +1397,18 @@ export interface PendingApproval {
   requestedAt: string;
 }
 
+/** Durable record of a tool call waiting on MCP authorization. */
+export interface PendingAuth {
+  callId: string;
+  turnId: string;
+  toolName: string;
+  connection: string;
+  authUrl: string;
+  requestedAt: string;
+}
+
 export type SessionEventPayload =
-  | { type: "session.started"; data: { channelId: string } }
+  | { type: "session.started"; data: { channelId: string; dryRun?: boolean } }
   | {
       /**
        * Sticky A/B enrollment for one experiment (`defineAB` under `agent/ab`).
@@ -1457,6 +1484,31 @@ export type SessionEventPayload =
         parentCallId?: string;
       };
     }
+  | {
+      /**
+       * A host MCP call/list needs OAuth. The turn stays running until
+       * the human completes the `authUrl` and the runtime retries.
+       */
+      type: "action.auth_requested";
+      data: {
+        callId: string;
+        toolName: string;
+        connection: string;
+        authUrl: string;
+        parentCallId?: string;
+      };
+    }
+  | {
+      type: "action.auth_resolved";
+      data: {
+        callId: string;
+        toolName: string;
+        connection: string;
+        decision: ApprovalDecision;
+        by?: string;
+        parentCallId?: string;
+      };
+    }
   | {
       type: "action.result";
       data: {
@@ -1586,6 +1638,8 @@ export interface SessionInfo {
   purpose?: SessionPurpose;
   /** True when write-classified tool calls are answered by the host. */
   dryRun?: boolean;
+  /** Frozen instant this session reads at; absent means the wall clock. */
+  asOf?: string;
   auth: AuthContext | null;
   title?: string;
   /**
@@ -1620,6 +1674,8 @@ export interface SessionRecord {
   purpose?: SessionPurpose;
   /** Frozen at create from {@link SendMessageOptions.dryRun}. */
   dryRun?: boolean;
+  /** Frozen at create from {@link SendMessageOptions.asOf}. */
+  asOf?: string;
   /**
    * Denormalized sticky A/B arms (mirrors durable `ab.assigned` events) so
    * the agent loop / tools can read arms without re-folding the log. Source
@@ -1672,6 +1728,11 @@ export interface SessionRecord {
    * SDK tool callback cannot be resumed after process restart).
    */
   pendingApprovals?: PendingApproval[];
+  /**
+   * Server-tool MCP calls parked for host or Cursor-account OAuth.
+   * Cleared when resolved or when the host restarts without a live waiter.
+   */
+  pendingAuths?: PendingAuth[];
   turnCount: number;
   createdAt: string;
   updatedAt: string;
@@ -1708,6 +1769,8 @@ export interface SessionSummary {
   queued?: boolean;
   createdAt: string;
   updatedAt: string;
+  /** True when write-classified tool calls are answered by the host. */
+  dryRun?: boolean;
   /** Active wire token for HTTP follow-ups, or null when not addressable. */
   continuationToken: string | null;
   /**
@@ -1808,6 +1871,13 @@ export interface SendMessageOptions {
    * model chose stay on the session log as the record of the intended action.
    */
   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.
+   */
+  asOf?: string;
   /**
    * Absolute directory used as the local harness `cwd` for this session.
    * On create, sets the session workspace. On resume (continuation hit),
@@ -1928,11 +1998,14 @@ export interface ToolCallOutcome {
   /** Present when the call ran inside an existing session. */
   sessionId?: string;
   /**
-   * Present (true) when a session-bound call could not materialize the
-   * session's harness cwd and ran in a scratch workspace instead. The
-   * session identity still applied (read-effect calls only get here), but
-   * `ctx.workspaceDir` was not the session workspace — callers rendering
-   * results as session state should surface this.
+   * Present (true) when a session-bound call could not materialize a
+   * session-owned harness cwd and ran in a scratch workspace instead.
+   * The session identity still applied (read-effect calls only get here),
+   * but `ctx.workspaceDir` was not the session workspace — callers
+   * rendering results as session state should surface this.
+   *
+   * A shared `local.workspaceDir` the host cannot create (a phantom path
+   * like `/repo`) is kept as-is and does not set this flag.
    */
   scratchWorkspace?: true;
 }
@@ -2187,6 +2260,18 @@ export interface ChannelStartArgs {
     auth: AuthContext | null,
     options?: { asSessionOwner?: boolean }
   ): Promise<PendingApproval>;
+  /**
+   * Mark a parked MCP auth as connected or cancelled. Channel packs
+   * (Slack "Connected") use this; the public OAuth callback also
+   * resolves after `finishAuth`.
+   */
+  resolveAuth(
+    sessionId: string,
+    callId: string,
+    decision: ApprovalDecision,
+    auth: AuthContext | null,
+    options?: { asSessionOwner?: boolean }
+  ): Promise<PendingAuth>;
   /**
    * Server log sink (same as {@link ServeOptions.logger}). Channel packs
    * should prefer this over `console.*` so CLI/eval hosts can redirect.

package/templates/agents-md/README.md

@@ -0,0 +1,39 @@
+# Living AGENTS.md
+
+Keeps `AGENTS.md` current from last week's merged pull requests and the
+listed Slack channels. Parks an update until a person approves it, then
+opens a draft follow-up PR. Chores stay quiet. Same-base updates stack
+on `agents-md/<base>`.
+
+```bash
+npx @cursor/july init ./agents-md --template agents-md
+```
+
+`init` asks which repo to watch and which Slack channels to read. Skip
+the prompt with `--var repos=owner/repo --var slack=#eng-api`.
+
+## Run
+
+Connect GitHub in Cursor for that repo. Create the Slack app and invite
+the bot to each listed channel, including private ones. Then sign the
+host in:
+
+```bash
+agent-sdk login
+agent-sdk slack create --dir .
+agent-sdk dev
+```
+
+Schedules do not fire under `dev`. Dispatch the weekly job:
+
+```bash
+curl -X POST http://127.0.0.1:3000/v1/dev/schedules/weekly
+```
+
+Or run `/queue/run` in the playground.
+
+## Files
+
+- `agent/lib/config.ts`: repo and Slack channels
+- `agent/instructions.md`: what counts as an AGENTS.md update
+- `evals/agents.eval.ts`: skip and update smoke cases