chore: refresh stale 1.22.1 doc examples after agent-server bump to 1.23.0 (#694)

AGENTS.md

@@ -322,10 +322,10 @@ return new ConversationClient(getAgentServerClientOptions()).someMethod(...);
 - `scripts/dev-safe.mjs` uses `uvx` for temporary agent-server installation — no permanent `uv tool install` needed. Environment variables (highest precedence first):
   - `OH_AGENT_SERVER_LOCAL_PATH` — absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.
   - `OH_AGENT_SERVER_GIT_REF` — git commit SHA or branch name (takes precedence over version)
-  - `OH_AGENT_SERVER_VERSION` — specific PyPI version (e.g., "1.22.1")
+  - `OH_AGENT_SERVER_VERSION` — specific PyPI version (e.g., "1.23.0")
   - `OH_SECRET_KEY` — secret key for settings encryption; uses a static default for local dev since it's needed for reading persisted encrypted values across restarts
   - `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` — session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)
-  - Default: released PyPI version `1.22.1` for agent-server SDK libraries
+  - Default: released PyPI version `1.23.0` for agent-server SDK libraries
 
 - Security: `scripts/dev-safe.mjs` and `scripts/dev-with-automation.mjs` auto-generate random API keys when needed and persist the defaults so static builds, localStorage, and restarted services stay in sync:
   - `SESSION_API_KEY` — 64-character hex (256-bit) for agent-server API authentication; persisted at `~/.openhands/agent-canvas/session-api-key.txt` unless overridden via env var

__tests__/scripts/docs-version-sync.test.ts

@@ -0,0 +1,63 @@
+// @vitest-environment node
+//
+// Drift-detection: documented agent-server version examples must match the
+// authoritative `versions.agentServer` pin in `config/defaults.json`.
+//
+// PR #670 bumped the central pin to 1.23.0 but left stale `1.22.1` examples in
+// AGENTS.md and several script JSDocs. This test fails when those references
+// drift from the central pin so the next bump cannot silently leave docs
+// behind.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+function read(rel: string): string {
+  return readFileSync(path.join(repoRoot, rel), "utf-8");
+}
+
+const config = JSON.parse(read("config/defaults.json")) as {
+  versions: { agentServer: string };
+};
+const v = config.versions.agentServer;
+
+describe("docs/example references stay in sync with config/defaults.json", () => {
+  it("AGENTS.md documents the current default version", () => {
+    const agentsMd = read("AGENTS.md");
+    expect(agentsMd).toContain(
+      `\`OH_AGENT_SERVER_VERSION\` — specific PyPI version (e.g., "${v}")`,
+    );
+    expect(agentsMd).toContain(
+      `Default: released PyPI version \`${v}\` for agent-server SDK libraries`,
+    );
+  });
+
+  it("scripts/dev-safe.mjs JSDoc example matches the current default", () => {
+    const devSafe = read("scripts/dev-safe.mjs");
+    expect(devSafe).toContain(
+      `OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "${v}")`,
+    );
+  });
+
+  it("scripts/check-sdk-version-sync.mjs examples match the current default", () => {
+    const src = read("scripts/check-sdk-version-sync.mjs");
+    expect(src).toContain(`EXPECTED_SDK_VERSION=${v}`);
+    expect(src).toContain(`"version": "${v}"`);
+    expect(src).toContain(`"openhands-sdk>=${v},<2.0.0"`);
+    expect(src).toContain(`"openhands-tools==${v}"`);
+    expect(src).toContain(`"openhands-workspace (>=${v})"`);
+    expect(src).toContain(
+      `">=${v}", "==${v}", "(>=${v})", "~=${v}"`,
+    );
+  });
+
+  it("scripts/check-acp-providers-sync.mjs --sdk-ref example matches the current default", () => {
+    const src = read("scripts/check-acp-providers-sync.mjs");
+    expect(src).toContain(`--sdk-ref v${v}`);
+  });
+});

scripts/check-acp-providers-sync.mjs

@@ -28,7 +28,7 @@
  *
  * Usage:
  *   node scripts/check-acp-providers-sync.mjs
- *   node scripts/check-acp-providers-sync.mjs --sdk-ref v1.22.1
+ *   node scripts/check-acp-providers-sync.mjs --sdk-ref v1.23.0
  *   node scripts/check-acp-providers-sync.mjs --sdk-file /path/to/acp_providers.py
  *
  * Options:

scripts/check-sdk-version-sync.mjs

@@ -19,7 +19,7 @@
  *
  * Usage:
  *   node scripts/check-sdk-version-sync.mjs
- *   EXPECTED_SDK_VERSION=1.22.1 node scripts/check-sdk-version-sync.mjs
+ *   EXPECTED_SDK_VERSION=1.23.0 node scripts/check-sdk-version-sync.mjs
  *   node scripts/check-sdk-version-sync.mjs --check-pypi
  *
  * Environment variables:
@@ -79,7 +79,7 @@ Triggering from other repos:
     -H "Authorization: token \$GITHUB_TOKEN" \\
     -H "Accept: application/vnd.github.v3+json" \\
     https://api.github.com/repos/OpenHands/agent-canvas/dispatches \\
-    -d '{"event_type": "sdk-version-check", "client_payload": {"version": "1.22.1"}}'
+    -d '{"event_type": "sdk-version-check", "client_payload": {"version": "1.23.0"}}'
 `);
   process.exit(0);
 }
@@ -268,9 +268,9 @@ async function fetchPyPIDependencies(packageName, version) {
  * Parse PyPI requires_dist array and extract SDK package versions
  *
  * PyPI returns dependencies in PEP 508 format like:
- *   "openhands-sdk>=1.22.1,<2.0.0"
- *   "openhands-tools==1.22.1"
- *   "openhands-workspace (>=1.22.1)"
+ *   "openhands-sdk>=1.23.0,<2.0.0"
+ *   "openhands-tools==1.23.0"
+ *   "openhands-workspace (>=1.23.0)"
  */
 function parseSdkVersionsFromRequiresDist(requiresDist) {
   const versions = {};
@@ -284,7 +284,7 @@ function parseSdkVersionsFromRequiresDist(requiresDist) {
       }
 
       // Extract the version number - look for patterns like:
-      // ">=1.22.1", "==1.22.1", "(>=1.22.1)", "~=1.22.1"
+      // ">=1.23.0", "==1.23.0", "(>=1.23.0)", "~=1.23.0"
       // After the package name and before any comma or closing paren
       const versionPattern = /[><=~!]+\s*([0-9]+(?:\.[0-9]+)*)/;
       const match = dep.match(versionPattern);

scripts/dev-safe.mjs

@@ -337,7 +337,7 @@ export function validateFrontendDependencies(
  *   edits are picked up without a manual reinstall. The agent-server itself
  *   is rebuilt from local source on each invocation (--reinstall).
  * - OH_AGENT_SERVER_GIT_REF: Git commit SHA or branch name
- * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.22.1")
+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.23.0")
  *
  * If none are set, defaults to the released version specified by
  * DEFAULT_AGENT_SERVER_VERSION. Set OH_AGENT_SERVER_GIT_REF to use a