langgraph-api 0.2.132__tar.gz → 0.2.135__tar.gz

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/Makefile

@@ -41,6 +41,8 @@ test-watch-oss:
 
 test: test-license-oss
 test-watch: test-watch-oss
+unit-test:
+	DATABASE_URI="test" REDIS_URI="test" uv run pytest tests/unit_tests
 
 test-auth:
 	LANGGRAPH_RUNTIME_EDITION=inmem LANGGRAPH_AUTH='{"path": "./tests/graphs/fastapi_jwt_auth.py:get_current_active_user"}' REDIS_URI=_FAKE DATABASE_URI=:memory: MIGRATIONS_PATH=__inmem__ uv run pytest -v $(AUTH_TEST)

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.2.132
+Version: 0.2.135
 Author-email: Nuno Campos <nuno@langchain.dev>, Will Fu-Hinthorn <will@langchain.dev>
 License: Elastic-2.0
 License-File: LICENSE
@@ -11,7 +11,7 @@ Requires-Dist: httpx>=0.25.0
 Requires-Dist: jsonschema-rs<0.30,>=0.20.0
 Requires-Dist: langchain-core>=0.3.64
 Requires-Dist: langgraph-checkpoint>=2.0.23
-Requires-Dist: langgraph-runtime-inmem<0.7,>=0.6.13
+Requires-Dist: langgraph-runtime-inmem<0.9.0,>=0.8.0
 Requires-Dist: langgraph-sdk>=0.2.0
 Requires-Dist: langgraph>=0.4.0
 Requires-Dist: langsmith>=0.3.45

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/benchmark/Makefile

@@ -1,14 +1,22 @@
 # Benchmark commands
 benchmark-burst:
+	make benchmark-reset
 	k6 run burst.js
 
 benchmark-ramp:
+	make benchmark-reset
 	k6 run --out json=raw_data_$(shell date +%Y-%m-%dT%H-%M-%S).json ramp.js
 
 benchmark-charts:
 	npm install
 	node graphs.js $(shell ls -t raw_data_*.json | head -1) true
 
+benchmark-reset:
+	node clean.js
+
+benchmark-new-revision:
+	node update-revision.js
+
 benchmark-clean:
 	rm -f results_*.json summary_*.json raw_data_*.json *_chart_*.png
 

langgraph_api-0.2.135/benchmark/clean.js

@@ -0,0 +1,87 @@
+/*
+ * Delete all threads and runs from the last benchmark run for consistent tests
+ * The default benchmark server has a thread TTL of one hour that should clean things up too so this doesn't run too long.
+ */
+
+// URL of your LangGraph server
+const BASE_URL = process.env.BASE_URL || 'http://localhost:9123';
+// LangSmith API key only needed with a custom server endpoint
+const LANGSMITH_API_KEY = process.env.LANGSMITH_API_KEY;
+
+async function clean() {
+    const headers = { 'Content-Type': 'application/json' };
+    if (LANGSMITH_API_KEY) {
+        headers['x-api-key'] = LANGSMITH_API_KEY;
+    }
+
+    const searchUrl = `${BASE_URL}/threads/search`;
+    let totalDeleted = 0;
+
+    try {
+        console.log('Starting thread cleanup...');
+        
+        while (true) {
+            try {
+                // Get the next page of threads
+                console.log('Searching for threads...');
+                const searchResponse = await fetch(searchUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        limit: 1000
+                    })
+                });
+
+                if (!searchResponse.ok) {
+                    throw new Error(`Search request failed: ${searchResponse.status} ${searchResponse.statusText}`);
+                }
+
+                const threads = await searchResponse.json();
+                
+                // If no threads found, we're done
+                if (!threads || threads.length === 0) {
+                    console.log('No more threads found.');
+                    break;
+                }
+
+                console.log(`Found ${threads.length} threads to delete`);
+
+                // Delete each thread
+                for (const thread of threads) {
+                    try {
+                        const deleteUrl = `${BASE_URL}/threads/${thread.thread_id}`;
+                        const deleteResponse = await fetch(deleteUrl, {
+                            method: 'DELETE',
+                            headers
+                        });
+
+                        if (!deleteResponse.ok) {
+                            console.error(`Failed to delete thread ${thread.thread_id}: ${deleteResponse.status} ${deleteResponse.statusText}`);
+                        } else {
+                            totalDeleted++;
+                        }
+                    } catch (deleteError) {
+                        console.error(`Error deleting thread ${thread.thread_id}:`, deleteError.message);
+                    }
+                }
+
+                console.log(`Deleted ${threads.length} threads in this batch`);
+
+            } catch (batchError) {
+                console.error('Error in batch processing:', batchError.message);
+                break;
+            }
+        }
+
+        console.log(`Cleanup completed. Total threads deleted: ${totalDeleted}`);
+
+    } catch (error) {
+        console.error('Fatal error during cleanup:', error.message);
+        process.exit(1);
+    }
+}
+
+clean().catch(error => {
+    console.error('Unhandled error:', error.message);
+    process.exit(1);
+});

langgraph_api-0.2.135/benchmark/update-revision.js

@@ -0,0 +1,148 @@
+/*
+ * Trigger a new revision deployment and wait for it to complete
+ * This ensures the benchmark instance is running the latest code
+ */
+
+// LangSmith API endpoints and credentials
+const DEPLOYMENT_ID = process.env.DEPLOYMENT_ID || 'a23f03ff-6d4d-4efd-8149-bb5a7f3b95cf'; // jdr-benchmark deployment id
+const LANGSMITH_API_KEY = process.env.LANGSMITH_API_KEY;
+const API_BASE = 'https://api.host.langchain.com/v1';
+
+// Deployment configuration
+const REVISION_CONFIG = {
+    repo_path: "langgraph.json",
+    env_vars: [
+        {
+            name: "N_JOBS_PER_WORKER",
+            value: "100",
+            value_from: "secret",
+            type: "secret"
+        }
+    ],
+    shareable: false,
+    container_spec: {
+        cpu: null,
+        memory_mb: null,
+        min_scale: 10,
+        max_scale: null
+    }
+};
+
+// Expected deployment statuses in order
+const EXPECTED_STATUSES = ['CREATED', 'AWAITING_BUILD', 'BUILDING', 'AWAITING_DEPLOY', 'DEPLOYING', 'DEPLOYED', 'QUEUED'];
+const FINAL_STATUS = 'DEPLOYED';
+const POLL_INTERVAL = 10000; // 10 seconds
+const MAX_WAIT_TIME = 30 * 60 * 1000; // 30 minutes
+
+async function updateRevision() {
+    if (!LANGSMITH_API_KEY) {
+        console.error('LANGSMITH_API_KEY environment variable is required');
+        process.exit(1);
+    }
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-api-key': LANGSMITH_API_KEY
+    };
+
+    const createUrl = `${API_BASE}/projects/${DEPLOYMENT_ID}/revisions`;
+    const pollUrl = `${API_BASE}/projects/${DEPLOYMENT_ID}/revisions?limit=1&offset=0`;
+
+    try {
+        console.log('Triggering new revision deployment...');
+        
+        // Step 1: Create new revision
+        const createResponse = await fetch(createUrl, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(REVISION_CONFIG)
+        });
+
+        if (createResponse.status === 409) {
+            console.log('⚠️  A new revision is already in progress. Continuing to poll existing deployment...');
+        } else if (!createResponse.ok) {
+            throw new Error(`Failed to create revision: ${createResponse.status} ${createResponse.statusText}`);
+        } else {
+            const newRevision = await createResponse.json();
+            const revisionId = newRevision.resource.latest_revision.hosted_langserve_revision_id;
+            console.log(`✓ New revision created: ${revisionId}`);
+            console.log(`Initial status: ${newRevision.status}`);
+        }
+
+        // Step 2: Poll until deployment is complete
+        console.log('\nPolling deployment status...');
+        const startTime = Date.now();
+        let lastStatus = null;
+
+        while (true) {
+            let pollResponse;
+            try {
+                pollResponse = await fetch(pollUrl, {
+                    method: 'GET',
+                    headers
+                });
+
+                if (!pollResponse.ok) {
+                    throw new Error(`Failed to poll revisions: ${pollResponse.status} ${pollResponse.statusText}`);
+                }
+            } catch (pollError) {
+                console.error('Error calling poll endpoint (will retry):', pollError.message);
+                // Wait before next poll and continue
+                await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL));
+                continue;
+            }
+
+            // Parse response and handle deployment logic (these errors should still be thrown)
+            const revisions = await pollResponse.json();
+            
+            if (!revisions || revisions.length === 0) {
+                throw new Error('No revisions found');
+            }
+
+            const latestRevision = revisions[0];
+            const currentStatus = latestRevision.status;
+
+            // Log status changes
+            if (currentStatus !== lastStatus) {
+                const timestamp = new Date().toISOString();
+                console.log(`[${timestamp}] Status: ${currentStatus}`);
+                
+                if (latestRevision.status_message) {
+                    console.log(`  Message: ${latestRevision.status_message}`);
+                }
+                
+                lastStatus = currentStatus;
+            }
+
+            // Check if deployment is complete
+            if (currentStatus === FINAL_STATUS) {
+                console.log(`\n✓ Deployment completed successfully!`);
+                console.log(`Revision ID: ${latestRevision.id}`);
+                console.log(`Total time: ${Math.round((Date.now() - startTime) / 1000)}s`);
+                break;
+            }
+
+            // Check for failure statuses
+            if (!EXPECTED_STATUSES.includes(currentStatus)) {
+                throw new Error(`Deployment failed with status: ${currentStatus}${latestRevision.status_message ? ` - ${latestRevision.status_message}` : ''}`);
+            }
+
+            // Check timeout
+            if (Date.now() - startTime > MAX_WAIT_TIME) {
+                throw new Error(`Deployment timeout after ${MAX_WAIT_TIME / 60000} minutes. Last status: ${currentStatus}`);
+            }
+
+            // Wait before next poll
+            await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL));
+        }
+
+    } catch (error) {
+        console.error('Fatal error during revision update:', error.message);
+        process.exit(1);
+    }
+}
+
+updateRevision().catch(error => {
+    console.error('Unhandled error:', error.message);
+    process.exit(1);
+});

langgraph_api-0.2.135/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.135"

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/langgraph_api/api/assistants.py

@@ -16,9 +16,16 @@ from langgraph_api.feature_flags import USE_RUNTIME_CONTEXT_API
 from langgraph_api.graph import get_assistant_id, get_graph
 from langgraph_api.js.base import BaseRemotePregel
 from langgraph_api.route import ApiRequest, ApiResponse, ApiRoute
+from langgraph_api.schema import ASSISTANT_FIELDS
 from langgraph_api.serde import ajson_loads
-from langgraph_api.utils import fetchone, get_pagination_headers, validate_uuid
+from langgraph_api.utils import (
+    fetchone,
+    get_pagination_headers,
+    validate_select_columns,
+    validate_uuid,
+)
 from langgraph_api.validation import (
+    AssistantCountRequest,
     AssistantCreate,
     AssistantPatch,
     AssistantSearchRequest,
@@ -173,6 +180,7 @@ async def search_assistants(
 ) -> ApiResponse:
     """List assistants."""
     payload = await request.json(AssistantSearchRequest)
+    select = validate_select_columns(payload.get("select") or None, ASSISTANT_FIELDS)
     offset = int(payload.get("offset") or 0)
     async with connect() as conn:
         assistants_iter, next_offset = await Assistants.search(
@@ -183,6 +191,7 @@ async def search_assistants(
             offset=offset,
             sort_by=payload.get("sort_by"),
             sort_order=payload.get("sort_order"),
+            select=select,
         )
     assistants, response_headers = await get_pagination_headers(
         assistants_iter, next_offset, offset
@@ -190,6 +199,21 @@ async def search_assistants(
     return ApiResponse(assistants, headers=response_headers)
 
 
+@retry_db
+async def count_assistants(
+    request: ApiRequest,
+) -> ApiResponse:
+    """Count assistants."""
+    payload = await request.json(AssistantCountRequest)
+    async with connect() as conn:
+        count = await Assistants.count(
+            conn,
+            graph_id=payload.get("graph_id"),
+            metadata=payload.get("metadata"),
+        )
+    return ApiResponse(count)
+
+
 @retry_db
 async def get_assistant(
     request: ApiRequest,
@@ -415,6 +439,7 @@ async def set_latest_assistant_version(request: ApiRequest) -> ApiResponse:
 assistants_routes: list[BaseRoute] = [
     ApiRoute("/assistants", create_assistant, methods=["POST"]),
     ApiRoute("/assistants/search", search_assistants, methods=["POST"]),
+    ApiRoute("/assistants/count", count_assistants, methods=["POST"]),
     ApiRoute(
         "/assistants/{assistant_id}/latest",
         set_latest_assistant_version,

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/langgraph_api/api/runs.py

@@ -10,9 +10,17 @@ from langgraph_api import config
 from langgraph_api.asyncio import ValueEvent, aclosing
 from langgraph_api.models.run import create_valid_run
 from langgraph_api.route import ApiRequest, ApiResponse, ApiRoute
+from langgraph_api.schema import CRON_FIELDS, RUN_FIELDS
 from langgraph_api.sse import EventSourceResponse
-from langgraph_api.utils import fetchone, get_pagination_headers, uuid7, validate_uuid
+from langgraph_api.utils import (
+    fetchone,
+    get_pagination_headers,
+    uuid7,
+    validate_select_columns,
+    validate_uuid,
+)
 from langgraph_api.validation import (
+    CronCountRequest,
     CronCreate,
     CronSearch,
     RunBatchCreate,
@@ -337,6 +345,9 @@ async def list_runs(
     limit = int(request.query_params.get("limit", 10))
     offset = int(request.query_params.get("offset", 0))
     status = request.query_params.get("status")
+    select = validate_select_columns(
+        request.query_params.getlist("select") or None, RUN_FIELDS
+    )
 
     async with connect() as conn, conn.pipeline():
         thread, runs = await asyncio.gather(
@@ -347,6 +358,7 @@ async def list_runs(
                 limit=limit,
                 offset=offset,
                 status=status,
+                select=select,
             ),
         )
     await fetchone(thread)
@@ -560,6 +572,7 @@ async def delete_cron(request: ApiRequest):
 async def search_crons(request: ApiRequest):
     """List all cron jobs for an assistant"""
     payload = await request.json(CronSearch)
+    select = validate_select_columns(payload.get("select") or None, CRON_FIELDS)
     if assistant_id := payload.get("assistant_id"):
         validate_uuid(assistant_id, "Invalid assistant ID: must be a UUID")
     if thread_id := payload.get("thread_id"):
@@ -575,6 +588,7 @@ async def search_crons(request: ApiRequest):
             offset=offset,
             sort_by=payload.get("sort_by"),
             sort_order=payload.get("sort_order"),
+            select=select,
         )
     crons, response_headers = await get_pagination_headers(
         crons_iter, next_offset, offset
@@ -582,6 +596,24 @@ async def search_crons(request: ApiRequest):
     return ApiResponse(crons, headers=response_headers)
 
 
+@retry_db
+async def count_crons(request: ApiRequest):
+    """Count cron jobs."""
+    payload = await request.json(CronCountRequest)
+    if assistant_id := payload.get("assistant_id"):
+        validate_uuid(assistant_id, "Invalid assistant ID: must be a UUID")
+    if thread_id := payload.get("thread_id"):
+        validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
+
+    async with connect() as conn:
+        count = await Crons.count(
+            conn,
+            assistant_id=assistant_id,
+            thread_id=thread_id,
+        )
+    return ApiResponse(count)
+
+
 runs_routes = [
     ApiRoute("/runs/stream", stream_run_stateless, methods=["POST"]),
     ApiRoute("/runs/wait", wait_run_stateless, methods=["POST"]),
@@ -598,6 +630,11 @@ runs_routes = [
         if config.FF_CRONS_ENABLED and plus_features_enabled()
         else None
     ),
+    (
+        ApiRoute("/runs/crons/count", count_crons, methods=["POST"])
+        if config.FF_CRONS_ENABLED and plus_features_enabled()
+        else None
+    ),
     ApiRoute("/threads/{thread_id}/runs/{run_id}/join", join_run, methods=["GET"]),
     ApiRoute(
         "/threads/{thread_id}/runs/{run_id}/stream",

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/langgraph_api/api/threads.py

@@ -5,9 +5,16 @@ from starlette.responses import Response
 from starlette.routing import BaseRoute
 
 from langgraph_api.route import ApiRequest, ApiResponse, ApiRoute
+from langgraph_api.schema import THREAD_FIELDS
 from langgraph_api.state import state_snapshot_to_thread_state
-from langgraph_api.utils import fetchone, get_pagination_headers, validate_uuid
+from langgraph_api.utils import (
+    fetchone,
+    get_pagination_headers,
+    validate_select_columns,
+    validate_uuid,
+)
 from langgraph_api.validation import (
+    ThreadCountRequest,
     ThreadCreate,
     ThreadPatch,
     ThreadSearchRequest,
@@ -58,6 +65,7 @@ async def search_threads(
 ):
     """List threads."""
     payload = await request.json(ThreadSearchRequest)
+    select = validate_select_columns(payload.get("select") or None, THREAD_FIELDS)
     limit = int(payload.get("limit") or 10)
     offset = int(payload.get("offset") or 0)
     async with connect() as conn:
@@ -70,6 +78,7 @@ async def search_threads(
             offset=offset,
             sort_by=payload.get("sort_by"),
             sort_order=payload.get("sort_order"),
+            select=select,
         )
     threads, response_headers = await get_pagination_headers(
         threads_iter, next_offset, offset
@@ -77,6 +86,22 @@ async def search_threads(
     return ApiResponse(threads, headers=response_headers)
 
 
+@retry_db
+async def count_threads(
+    request: ApiRequest,
+):
+    """Count threads."""
+    payload = await request.json(ThreadCountRequest)
+    async with connect() as conn:
+        count = await Threads.count(
+            conn,
+            status=payload.get("status"),
+            values=payload.get("values"),
+            metadata=payload.get("metadata"),
+        )
+    return ApiResponse(count)
+
+
 @retry_db
 async def get_thread_state(
     request: ApiRequest,
@@ -260,6 +285,7 @@ async def copy_thread(request: ApiRequest):
 threads_routes: list[BaseRoute] = [
     ApiRoute("/threads", endpoint=create_thread, methods=["POST"]),
     ApiRoute("/threads/search", endpoint=search_threads, methods=["POST"]),
+    ApiRoute("/threads/count", endpoint=count_threads, methods=["POST"]),
     ApiRoute("/threads/{thread_id}", endpoint=get_thread, methods=["GET"]),
     ApiRoute("/threads/{thread_id}", endpoint=patch_thread, methods=["PATCH"]),
     ApiRoute("/threads/{thread_id}", endpoint=delete_thread, methods=["DELETE"]),

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/langgraph_api/js/package.json

@@ -11,8 +11,8 @@
     "@hono/zod-validator": "^0.2.2",
     "@langchain/core": "^0.3.59",
     "@langchain/langgraph": "^0.2.65",
-    "@langchain/langgraph-api": "~0.0.56",
-    "@langchain/langgraph-ui": "~0.0.56",
+    "@langchain/langgraph-api": "~0.0.59",
+    "@langchain/langgraph-ui": "~0.0.59",
     "@langchain/langgraph-checkpoint": "~0.0.18",
     "@types/json-schema": "^7.0.15",
     "@typescript/vfs": "^1.6.0",

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/langgraph_api/js/yarn.lock

@@ -203,15 +203,15 @@
     zod "^3.25.32"
     zod-to-json-schema "^3.22.3"
 
-"@langchain/langgraph-api@~0.0.56":
-  version "0.0.56"
-  resolved "https://registry.yarnpkg.com/@langchain/langgraph-api/-/langgraph-api-0.0.56.tgz#9e0a6e5dd9af2f6ec259a32ca9081b19457a0825"
-  integrity sha512-BhrbMKSc3f4CXXDXgvHR8mE2bsgD/G6dDzr+yDkEC7a9eeFI7C8bPhkGmegFJ+q7i6GWtqlQOYSCWHqQFZxynQ==
+"@langchain/langgraph-api@~0.0.59":
+  version "0.0.59"
+  resolved "https://registry.yarnpkg.com/@langchain/langgraph-api/-/langgraph-api-0.0.59.tgz#a3d69b8cc68ceebd8a8d86b77abd03924ddcd02c"
+  integrity sha512-pUt3yKB2z1nsXdhqpRQgVefYg5MdJVsqH64gTNzSb/JYJBPIUj2h8XttRx9+3mHtVqCzvL2bb+HVIterNFOKtw==
   dependencies:
     "@babel/code-frame" "^7.26.2"
     "@hono/node-server" "^1.12.0"
     "@hono/zod-validator" "^0.2.2"
-    "@langchain/langgraph-ui" "0.0.56"
+    "@langchain/langgraph-ui" "0.0.59"
     "@types/json-schema" "^7.0.15"
     "@typescript/vfs" "^1.6.0"
     dedent "^1.5.3"
@@ -256,10 +256,10 @@
     p-retry "4"
     uuid "^9.0.0"
 
-"@langchain/langgraph-ui@0.0.56", "@langchain/langgraph-ui@~0.0.56":
-  version "0.0.56"
-  resolved "https://registry.yarnpkg.com/@langchain/langgraph-ui/-/langgraph-ui-0.0.56.tgz#b566afa4ad940fc6bd942205a00b3afac7fd7363"
-  integrity sha512-cRU+fMCz1NAOjRLcreNa64Gap89yio0p8baRigehtL1SNsXJEaZ2xdGjbnjaWIl8rTrriDak4oisx07whwcBjQ==
+"@langchain/langgraph-ui@0.0.59", "@langchain/langgraph-ui@~0.0.59":
+  version "0.0.59"
+  resolved "https://registry.yarnpkg.com/@langchain/langgraph-ui/-/langgraph-ui-0.0.59.tgz#41988eae48c7520c5ebfa9bcdda65ddadfe1aab9"
+  integrity sha512-x6Jqt7TZRfHGU0MyxVbz7ugucT/oJQm9kM+DlGdmfAEm2JrNqgy1W85E589xJCJjpuRiDLpP7NiqSwnp8lCEqg==
   dependencies:
     "@commander-js/extra-typings" "^13.0.0"
     commander "^13.0.0"

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/langgraph_api/route.py

@@ -97,7 +97,8 @@ class ApiRoute(Route):
         include_in_schema: bool = True,
         middleware: typing.Sequence[Middleware] | None = None,
     ) -> None:
-        assert path.startswith("/"), "Routed paths must start with '/'"
+        if not path.startswith("/"):
+            raise ValueError("Routed paths must start with '/'")
         self.path = path
         self.endpoint = endpoint
         self.name = get_name(endpoint) if name is None else name

{langgraph_api-0.2.132 → langgraph_api-0.2.135}/langgraph_api/schema.py

@@ -1,6 +1,6 @@
 from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, Literal, Optional, TypeAlias
+from typing import Any, Literal, NotRequired, Optional, TypeAlias
 from uuid import UUID
 
 from langchain_core.runnables.config import RunnableConfig
@@ -121,6 +121,8 @@ class Thread(TypedDict):
     """The thread metadata."""
     config: Fragment
     """The thread config."""
+    context: Fragment
+    """The thread context."""
     status: ThreadStatus
     """The status of the thread. One of 'idle', 'busy', 'interrupted', "error"."""
     values: Fragment
@@ -223,16 +225,16 @@ class Cron(TypedDict):
     """The time the cron was created."""
     updated_at: datetime
     """The last time the cron was updated."""
-    user_id: UUID | None
-    """The ID of the user."""
+    user_id: str | None
+    """The ID of the user (string identity)."""
     payload: Fragment
     """The run payload to use for creating new run."""
     next_run_date: datetime
     """The next run date of the cron."""
     metadata: Fragment
     """The cron metadata."""
-    now: datetime
-    """The current time."""
+    now: NotRequired[datetime]
+    """The current time (present in internal next() only)."""
 
 
 class ThreadUpdateResponse(TypedDict):
@@ -246,3 +248,66 @@ class QueueStats(TypedDict):
     n_running: int
     max_age_secs: datetime | None
     med_age_secs: datetime | None
+
+
+# Canonical field sets for select= validation and type aliases for ops
+
+# Assistant select fields (intentionally excludes 'context')
+AssistantSelectField = Literal[
+    "assistant_id",
+    "graph_id",
+    "name",
+    "description",
+    "config",
+    "context",
+    "created_at",
+    "updated_at",
+    "metadata",
+    "version",
+]
+ASSISTANT_FIELDS: set[str] = set(AssistantSelectField.__args__)  # type: ignore[attr-defined]
+
+# Thread select fields
+ThreadSelectField = Literal[
+    "thread_id",
+    "created_at",
+    "updated_at",
+    "metadata",
+    "config",
+    "context",
+    "status",
+    "values",
+    "interrupts",
+]
+THREAD_FIELDS: set[str] = set(ThreadSelectField.__args__)  # type: ignore[attr-defined]
+
+# Run select fields
+RunSelectField = Literal[
+    "run_id",
+    "thread_id",
+    "assistant_id",
+    "created_at",
+    "updated_at",
+    "status",
+    "metadata",
+    "kwargs",
+    "multitask_strategy",
+]
+RUN_FIELDS: set[str] = set(RunSelectField.__args__)  # type: ignore[attr-defined]
+
+# Cron select fields
+CronSelectField = Literal[
+    "cron_id",
+    "assistant_id",
+    "thread_id",
+    "end_time",
+    "schedule",
+    "created_at",
+    "updated_at",
+    "user_id",
+    "payload",
+    "next_run_date",
+    "metadata",
+    "now",
+]
+CRON_FIELDS: set[str] = set(CronSelectField.__args__)  # type: ignore[attr-defined]