antigravity-sidecar-kit 1.0.3 → 1.1.0

package/README.md

@@ -13,7 +13,7 @@ Google Antigravity's built-in `sidecar_sdk` provides a minimal `SidecarApp` loop
 Generate a complete, Hangar-compatible Antigravity Auxiliary Pane sidecar in one command:
 
 ```bash
-npx antigravity-sidecar-kit init my-sidecar
+npm create antigravity-sidecar my-sidecar
 cd antigravity-my-sidecar
 npm install
 npm run setup
@@ -21,6 +21,8 @@ npm run setup
 
 Options: `--dir <target-dir>` to choose the output folder, `--force` to overwrite an existing scaffold.
 
+`npm create antigravity-sidecar` runs the [`create-antigravity-sidecar`](https://www.npmjs.com/package/create-antigravity-sidecar) launcher. `npx antigravity-sidecar-kit init my-sidecar` does the same thing.
+
 What gets generated:
 - `package.json` — ESM configuration with `setup`, `start`, `uninstall`, and `test` scripts.
 - `sidecar.json` — Antigravity `SidecarManager` manifest (`SIDECAR_UI_ENTRYPOINT_AUX_PANE`).
@@ -88,6 +90,18 @@ await manageSidecar('my-sidecar', 'SIDECAR_ACTION_RESTART');
 const customRes = await callLsRpc('GetMcpServerStates', {});
 ```
 
+- **Cached & Deduplicated Calls (`createLsRpcCache`)**: Opt-in wrapper for RPCs your UI polls. Concurrent calls with the same method and body share one in-flight request, and successful results are kept for a per-method TTL (failures are never cached). The cache lives in your sidecar's Node process, so every iframe of that sidecar shares it. Cached results are shared objects: treat them as read-only.
+
+  ```js
+  import { createLsRpcCache } from 'antigravity-sidecar-kit/rpc';
+
+  const lsCache = createLsRpcCache({
+    ttlMs: { GetUserStatus: 30_000, GetCascadeTrajectorySteps: 2_000 },
+    defaultTtlMs: 0, // unlisted methods: only merge concurrent calls
+  });
+  const status = await lsCache.call('GetUserStatus', {});
+  lsCache.invalidate('GetUserStatus'); // after a write that changes it; invalidate() clears all
+  ```
 - **Automatic Credential Persistence**: When imported inside a running sidecar daemon (`ANTIGRAVITY_SIDECAR_WEB_PORT` + `ANTIGRAVITY_LS_ADDRESS`), `persistSidecarRuntime` caches `{ pid, webPort, lsAddress, csrfToken }` to `~/.gemini/antigravity/sidecar_data/<id>/data/runtime.json` (owner-only, mode `0600` on macOS/Linux) so CLI tools (`setup.mjs`) invoked from external terminals can talk to the Language Server even when env vars aren't exported in the user's shell.
 - **Fallback Process Restarter (`killSidecarProcessByPortOrPid`)**: If the Language Server RPC is unreachable from an external terminal, sends `SIGTERM` to the sidecar so Antigravity's `"restart_policy": "always"` respawns the updated version. It only kills a process it can verify: the `runtime.json` PID must still own the recorded `webPort`, and when the port only comes from `logs/sidecar.log`, only `node` processes listening on it are stopped. A stale `runtime.json` is ignored.
 

package/lib/rpc.mjs

@@ -258,6 +258,64 @@ export async function callLsRpc(method, body = {}, options = {}) {
   return parsed;
 }
 
+/**
+ * Opt-in cache in front of callLsRpc. Concurrent calls with the same method and body share one
+ * in-flight request, and successful results are kept for that method's TTL. Failures are never
+ * cached. Cached results are shared between callers, so treat them as read-only.
+ *
+ * @param {object} [opts]
+ * @param {Record<string, number>} [opts.ttlMs] Per-method TTL in ms; 0 only merges in-flight calls.
+ * @param {number} [opts.defaultTtlMs] TTL for methods missing from `ttlMs`.
+ * @param {Function} [opts.rpcFn] Underlying call, `(method, body, options) => Promise`.
+ * @param {Function} [opts.now] Clock, for tests.
+ * @returns {{ call: Function, invalidate: Function }} `invalidate(...methods)` drops those
+ *   methods' entries (in flight or cached), or every entry when called with no arguments.
+ */
+export function createLsRpcCache({ ttlMs = {}, defaultTtlMs = 0, rpcFn = callLsRpc, now = Date.now } = {}) {
+  const entries = new Map();
+
+  function call(method, body = {}, options = {}) {
+    // One cache line per Language Server; the token, timeout and fetchFn don't change the answer
+    const key = `${getLsConfig(options).lsAddress}\n${method}\n${JSON.stringify(body)}`;
+    const hit = entries.get(key);
+    if (hit && (hit.pending || now() < hit.expiresAt)) return hit.promise;
+
+    const ttl = ttlMs[method] ?? defaultTtlMs;
+    const entry = { method, pending: true, expiresAt: 0, promise: null };
+    entry.promise = Promise.resolve()
+      .then(() => rpcFn(method, body, options))
+      .then(
+        (result) => {
+          // invalidate() ran during the call: keep the stale answer out of the cache
+          if (entries.get(key) === entry) {
+            entry.pending = false;
+            entry.expiresAt = now() + ttl;
+            if (ttl <= 0) entries.delete(key);
+          }
+          return result;
+        },
+        (err) => {
+          if (entries.get(key) === entry) entries.delete(key);
+          throw err;
+        }
+      );
+    entries.set(key, entry);
+    return entry.promise;
+  }
+
+  function invalidate(...methods) {
+    if (methods.length === 0) {
+      entries.clear();
+      return;
+    }
+    for (const [key, entry] of entries) {
+      if (methods.includes(entry.method)) entries.delete(key);
+    }
+  }
+
+  return { call, invalidate };
+}
+
 export const getSidecars = (options = {}) => callLsRpc('GetSidecars', {}, options);
 export const manageSidecar = (sidecarId, action, options = {}) =>
   callLsRpc('ManageSidecar', { action, sidecarId }, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antigravity-sidecar-kit",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "type": "module",
   "description": "Zero-dependency SDK and CLI scaffolder for Google Antigravity Auxiliary Pane sidecars (Connect RPC client, host theme & Tailwind proxy, BOM-safe config store, workspace URI matcher, and npx-safe installer).",
   "license": "MIT",