@agent-native/core 0.36.0 → 0.37.1

package/dist/client/route-state.d.ts

@@ -0,0 +1,116 @@
+import { type QueryKey } from "@tanstack/react-query";
+import { type Location, type NavigateOptions } from "react-router";
+export interface SemanticNavigationCommandEnvelope<NavigateCommand> {
+    key: string;
+    command: NavigateCommand;
+}
+export interface UseSemanticNavigationStateOptions<NavigationState, NavigateCommand = NavigationState> {
+    /**
+     * Compact, semantic screen state to expose to the agent: view names, record
+     * IDs, active tabs, and useful aliases. Keep URL query params in the URL
+     * unless the app needs a human-readable semantic alias.
+     */
+    state: NavigationState | null | undefined;
+    /** Application-state keys the UI should write. Defaults to [`navigation`]. */
+    navigationKeys?: readonly string[];
+    /** Application-state keys to read for one-shot agent commands. Defaults to [`navigate`]. */
+    commandKeys?: readonly string[];
+    /** React Query key used for command polling/cache. Defaults to [`navigate-command`]. */
+    commandQueryKey?: QueryKey;
+    /** Request source tag for `useDbSync({ ignoreSource })` jitter prevention. */
+    requestSource?: string;
+    /** Poll interval for command reads. Defaults to 2000ms. Pass false to disable polling. */
+    commandRefetchInterval?: number | false;
+    /** Disable both navigation writes and command reads. */
+    enabled?: boolean;
+    /** Navigation writes use keepalive by default because they often fire during unload. */
+    keepalive?: boolean;
+    /** Debounce navigation writes. Defaults to 0ms. */
+    writeDebounceMs?: number;
+    /** Custom duplicate-command key. Defaults to `_writeId` or JSON content. */
+    getCommandDedupKey?: (command: NavigateCommand) => string;
+    /** Called once for each non-duplicate command after the command is consumed. */
+    onCommand: (command: NavigateCommand) => void | Promise<void>;
+    /** Optional sink for best-effort navigation write/read/delete/command errors. */
+    onError?: (error: unknown) => void;
+}
+export interface UseSemanticNavigationStateResult<NavigationState, NavigateCommand = NavigationState> {
+    navigationState: NavigationState | null;
+    command: SemanticNavigationCommandEnvelope<NavigateCommand> | null | undefined;
+    commandQueryKey: QueryKey;
+    clearCommand: () => Promise<void>;
+}
+export interface AgentRouteLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+    searchParams: URLSearchParams;
+    location: Location;
+}
+export interface UseAgentRouteStateOptions<NavigationState, NavigateCommand = NavigationState> {
+    /**
+     * Derive compact, semantic screen state from the current React Router URL.
+     * The framework separately exposes raw `pathname`, `search`, and parsed
+     * `searchParams` through `<current-url>`.
+     */
+    getNavigationState: (location: AgentRouteLocation) => NavigationState | null | undefined;
+    /**
+     * Convert an agent-authored one-shot command into an app-local React Router
+     * path. Return null to consume and ignore malformed or unsupported commands.
+     */
+    getCommandPath: (command: NavigateCommand) => string | null | undefined;
+    /** Application-state key the UI writes. Defaults to `navigation`. */
+    navigationKey?: string;
+    /** Application-state key the agent writes for one-shot navigation. */
+    commandKey?: string;
+    /** Current browser tab id. Enables tab-scoped reads/writes. */
+    browserTabId?: string;
+    /** Request source tag for `useDbSync({ ignoreSource })` jitter prevention. */
+    requestSource?: string;
+    /**
+     * Also write the unscoped navigation key when browserTabId is present.
+     * Defaults to true so CLI/external agents still have a useful fallback.
+     */
+    writeGlobalNavigation?: boolean;
+    /**
+     * Fall back to the unscoped command key when no tab-scoped command exists.
+     * Defaults to true for backwards compatibility with existing navigate tools.
+     */
+    readGlobalCommandFallback?: boolean;
+    /** React Query key used for command polling/cache. */
+    commandQueryKey?: QueryKey;
+    /** Poll interval for command reads. Defaults to 2000ms. Pass false to disable polling. */
+    refetchInterval?: number | false;
+    /** Disable both navigation writes and command reads. */
+    enabled?: boolean;
+    /** Navigation writes use keepalive by default because they often fire during unload. */
+    keepalive?: boolean;
+    /** Debounce navigation writes. Defaults to 0ms. */
+    writeDebounceMs?: number;
+    /** Custom duplicate-command key. Defaults to `_writeId` or JSON content. */
+    getCommandDedupKey?: (command: NavigateCommand) => string;
+    /** React Router navigate options, or a function of the consumed command. */
+    navigateOptions?: NavigateOptions | ((command: NavigateCommand) => NavigateOptions | undefined);
+    /** Called after a command is consumed and before React Router navigation. */
+    onNavigate?: (command: NavigateCommand, path: string) => void;
+    /** Optional sink for best-effort navigation write/read/delete errors. */
+    onError?: (error: unknown) => void;
+}
+export interface UseAgentRouteStateResult<NavigationState, NavigateCommand = NavigationState> extends UseSemanticNavigationStateResult<NavigationState, NavigateCommand> {
+}
+/**
+ * Keeps semantic UI state agent-visible and consumes agent-authored one-shot
+ * commands. This is the framework primitive behind route/navigation sync; it
+ * intentionally knows nothing about app-specific route shapes.
+ */
+export declare function useSemanticNavigationState<NavigationState, NavigateCommand = NavigationState>(options: UseSemanticNavigationStateOptions<NavigationState, NavigateCommand>): UseSemanticNavigationStateResult<NavigationState, NavigateCommand>;
+/**
+ * React Router convenience wrapper around `useSemanticNavigationState`.
+ *
+ * Use URL query params as the source of truth for shareable filters. This hook
+ * writes semantic aliases and stable IDs to `navigation`; the framework's
+ * built-in URL sync separately exposes raw `pathname`, `search`, and
+ * `searchParams` through `<current-url>` and the `set-search-params` tool.
+ */
+export declare function useAgentRouteState<NavigationState, NavigateCommand = NavigationState>(options: UseAgentRouteStateOptions<NavigationState, NavigateCommand>): UseAgentRouteStateResult<NavigationState, NavigateCommand>;
+//# sourceMappingURL=route-state.d.ts.map

package/dist/client/route-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-state.d.ts","sourceRoot":"","sources":["../../src/client/route-state.ts"],"names":[],"mappings":"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"}

package/dist/client/route-state.js

@@ -0,0 +1,205 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useLocation, useNavigate, } from "react-router";
+import { deleteClientAppState, readClientAppState, setClientAppState, } from "./application-state.js";
+const SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;
+function normalizeBrowserTabId(browserTabId) {
+    if (typeof browserTabId !== "string")
+        return undefined;
+    const trimmed = browserTabId.trim();
+    return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? trimmed : undefined;
+}
+function appStateKeyForBrowserTab(key, browserTabId) {
+    return browserTabId ? `${key}:${browserTabId}` : key;
+}
+function routeLocationFromReactRouter(location) {
+    return {
+        pathname: location.pathname,
+        search: location.search,
+        hash: location.hash,
+        searchParams: new URLSearchParams(location.search),
+        location,
+    };
+}
+function uniqueKeys(keys) {
+    return Array.from(new Set(keys));
+}
+function defaultCommandDedupKey(command) {
+    if (command && typeof command === "object" && "_writeId" in command) {
+        const writeId = command._writeId;
+        if (typeof writeId === "string" && writeId)
+            return writeId;
+    }
+    return JSON.stringify(command);
+}
+function currentRouterPath(location) {
+    return `${location.pathname}${location.search}${location.hash}`;
+}
+function stringifyForWriteDedup(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Keeps semantic UI state agent-visible and consumes agent-authored one-shot
+ * commands. This is the framework primitive behind route/navigation sync; it
+ * intentionally knows nothing about app-specific route shapes.
+ */
+export function useSemanticNavigationState(options) {
+    const { requestSource, commandRefetchInterval = 2_000, enabled = true, keepalive = true, writeDebounceMs = 0, } = options;
+    const queryClient = useQueryClient();
+    const navigationKeys = useMemo(() => uniqueKeys(options.navigationKeys ?? ["navigation"]), [options.navigationKeys]);
+    const commandKeys = useMemo(() => uniqueKeys(options.commandKeys ?? ["navigate"]), [options.commandKeys]);
+    const commandQueryKey = useMemo(() => options.commandQueryKey ?? ["navigate-command"], [options.commandQueryKey]);
+    const navigationState = options.state ?? null;
+    const navigationWriteDedup = stringifyForWriteDedup({
+        keys: navigationKeys,
+        state: navigationState,
+    });
+    const getCommandDedupKeyRef = useRef(options.getCommandDedupKey);
+    const onCommandRef = useRef(options.onCommand);
+    const onErrorRef = useRef(options.onError);
+    getCommandDedupKeyRef.current = options.getCommandDedupKey;
+    onCommandRef.current = options.onCommand;
+    onErrorRef.current = options.onError;
+    const lastNavigationWriteRef = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (lastNavigationWriteRef.current === navigationWriteDedup)
+            return;
+        lastNavigationWriteRef.current = navigationWriteDedup;
+        const write = () => {
+            for (const key of navigationKeys) {
+                setClientAppState(key, navigationState, {
+                    keepalive,
+                    requestSource,
+                }).catch((error) => onErrorRef.current?.(error));
+            }
+        };
+        if (writeDebounceMs > 0) {
+            const timer = setTimeout(write, writeDebounceMs);
+            return () => clearTimeout(timer);
+        }
+        write();
+    }, [
+        enabled,
+        keepalive,
+        navigationKeys,
+        navigationState,
+        navigationWriteDedup,
+        requestSource,
+        writeDebounceMs,
+    ]);
+    const commandQuery = useQuery({
+        queryKey: commandQueryKey,
+        enabled,
+        retry: false,
+        refetchInterval: commandRefetchInterval,
+        queryFn: async () => {
+            for (const key of commandKeys) {
+                const command = await readClientAppState(key);
+                if (command !== null && command !== undefined) {
+                    return { key, command };
+                }
+            }
+            return null;
+        },
+    });
+    const clearCommand = useCallback(async () => {
+        await Promise.all(commandKeys.map((key) => deleteClientAppState(key, { requestSource }).catch((error) => {
+            onErrorRef.current?.(error);
+        })));
+        queryClient.setQueryData(commandQueryKey, null);
+    }, [commandKeys, commandQueryKey, queryClient, requestSource]);
+    const lastProcessedDedupKeyRef = useRef(null);
+    useEffect(() => {
+        const envelope = commandQuery.data;
+        if (!enabled || !envelope)
+            return;
+        const dedupKey = getCommandDedupKeyRef.current?.(envelope.command) ??
+            defaultCommandDedupKey(envelope.command);
+        const consume = () => {
+            deleteClientAppState(envelope.key, { requestSource }).catch((error) => onErrorRef.current?.(error));
+            queryClient.setQueryData(commandQueryKey, null);
+        };
+        if (lastProcessedDedupKeyRef.current === dedupKey) {
+            consume();
+            return;
+        }
+        lastProcessedDedupKeyRef.current = dedupKey;
+        consume();
+        Promise.resolve(onCommandRef.current(envelope.command)).catch((error) => onErrorRef.current?.(error));
+    }, [commandQuery.data, commandQueryKey, enabled, queryClient, requestSource]);
+    return {
+        navigationState,
+        command: commandQuery.data,
+        commandQueryKey,
+        clearCommand,
+    };
+}
+/**
+ * React Router convenience wrapper around `useSemanticNavigationState`.
+ *
+ * Use URL query params as the source of truth for shareable filters. This hook
+ * writes semantic aliases and stable IDs to `navigation`; the framework's
+ * built-in URL sync separately exposes raw `pathname`, `search`, and
+ * `searchParams` through `<current-url>` and the `set-search-params` tool.
+ */
+export function useAgentRouteState(options) {
+    const { navigationKey = "navigation", commandKey = "navigate", writeGlobalNavigation = true, readGlobalCommandFallback = true, } = options;
+    const location = useLocation();
+    const navigate = useNavigate();
+    const browserTabId = useMemo(() => normalizeBrowserTabId(options.browserTabId), [options.browserTabId]);
+    const navigationKeys = useMemo(() => {
+        const scopedKey = appStateKeyForBrowserTab(navigationKey, browserTabId);
+        const keys = [scopedKey];
+        if (browserTabId && writeGlobalNavigation)
+            keys.push(navigationKey);
+        return uniqueKeys(keys);
+    }, [browserTabId, navigationKey, writeGlobalNavigation]);
+    const commandKeys = useMemo(() => {
+        const scopedKey = appStateKeyForBrowserTab(commandKey, browserTabId);
+        const keys = [scopedKey];
+        if (browserTabId && readGlobalCommandFallback)
+            keys.push(commandKey);
+        return uniqueKeys(keys);
+    }, [browserTabId, commandKey, readGlobalCommandFallback]);
+    const commandQueryKey = useMemo(() => options.commandQueryKey ?? [
+        "navigate-command",
+        commandKey,
+        browserTabId ?? "global",
+    ], [browserTabId, commandKey, options.commandQueryKey]);
+    const routeLocation = useMemo(() => routeLocationFromReactRouter(location), [location]);
+    const navigationState = options.getNavigationState(routeLocation) ?? null;
+    return useSemanticNavigationState({
+        state: navigationState,
+        navigationKeys,
+        commandKeys,
+        commandQueryKey,
+        requestSource: options.requestSource,
+        commandRefetchInterval: options.refetchInterval,
+        enabled: options.enabled,
+        keepalive: options.keepalive,
+        writeDebounceMs: options.writeDebounceMs,
+        getCommandDedupKey: options.getCommandDedupKey,
+        onError: options.onError,
+        onCommand: (command) => {
+            const path = options.getCommandPath(command);
+            if (!path)
+                return;
+            options.onNavigate?.(command, path);
+            if (path === currentRouterPath(location))
+                return;
+            const navigateOptions = options.navigateOptions;
+            const resolvedOptions = typeof navigateOptions === "function"
+                ? navigateOptions(command)
+                : navigateOptions;
+            navigate(path, resolvedOptions);
+        },
+    });
+}
+//# sourceMappingURL=route-state.js.map

package/dist/client/route-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-state.js","sourceRoot":"","sources":["../../src/client/route-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useMemo, useRef } from \"react\";\nimport { useQuery, useQueryClient, type QueryKey } from \"@tanstack/react-query\";\nimport {\n  useLocation,\n  useNavigate,\n  type Location,\n  type NavigateOptions,\n} from \"react-router\";\nimport {\n  deleteClientAppState,\n  readClientAppState,\n  setClientAppState,\n} from \"./application-state.js\";\n\nconst SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;\n\nexport interface SemanticNavigationCommandEnvelope<NavigateCommand> {\n  key: string;\n  command: NavigateCommand;\n}\n\nexport interface UseSemanticNavigationStateOptions<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> {\n  /**\n   * Compact, semantic screen state to expose to the agent: view names, record\n   * IDs, active tabs, and useful aliases. Keep URL query params in the URL\n   * unless the app needs a human-readable semantic alias.\n   */\n  state: NavigationState | null | undefined;\n  /** Application-state keys the UI should write. Defaults to [`navigation`]. */\n  navigationKeys?: readonly string[];\n  /** Application-state keys to read for one-shot agent commands. Defaults to [`navigate`]. */\n  commandKeys?: readonly string[];\n  /** React Query key used for command polling/cache. Defaults to [`navigate-command`]. */\n  commandQueryKey?: QueryKey;\n  /** Request source tag for `useDbSync({ ignoreSource })` jitter prevention. */\n  requestSource?: string;\n  /** Poll interval for command reads. Defaults to 2000ms. Pass false to disable polling. */\n  commandRefetchInterval?: number | false;\n  /** Disable both navigation writes and command reads. */\n  enabled?: boolean;\n  /** Navigation writes use keepalive by default because they often fire during unload. */\n  keepalive?: boolean;\n  /** Debounce navigation writes. Defaults to 0ms. */\n  writeDebounceMs?: number;\n  /** Custom duplicate-command key. Defaults to `_writeId` or JSON content. */\n  getCommandDedupKey?: (command: NavigateCommand) => string;\n  /** Called once for each non-duplicate command after the command is consumed. */\n  onCommand: (command: NavigateCommand) => void | Promise<void>;\n  /** Optional sink for best-effort navigation write/read/delete/command errors. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface UseSemanticNavigationStateResult<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> {\n  navigationState: NavigationState | null;\n  command:\n    | SemanticNavigationCommandEnvelope<NavigateCommand>\n    | null\n    | undefined;\n  commandQueryKey: QueryKey;\n  clearCommand: () => Promise<void>;\n}\n\nexport interface AgentRouteLocation {\n  pathname: string;\n  search: string;\n  hash: string;\n  searchParams: URLSearchParams;\n  location: Location;\n}\n\nexport interface UseAgentRouteStateOptions<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> {\n  /**\n   * Derive compact, semantic screen state from the current React Router URL.\n   * The framework separately exposes raw `pathname`, `search`, and parsed\n   * `searchParams` through `<current-url>`.\n   */\n  getNavigationState: (\n    location: AgentRouteLocation,\n  ) => NavigationState | null | undefined;\n  /**\n   * Convert an agent-authored one-shot command into an app-local React Router\n   * path. Return null to consume and ignore malformed or unsupported commands.\n   */\n  getCommandPath: (command: NavigateCommand) => string | null | undefined;\n  /** Application-state key the UI writes. Defaults to `navigation`. */\n  navigationKey?: string;\n  /** Application-state key the agent writes for one-shot navigation. */\n  commandKey?: string;\n  /** Current browser tab id. Enables tab-scoped reads/writes. */\n  browserTabId?: string;\n  /** Request source tag for `useDbSync({ ignoreSource })` jitter prevention. */\n  requestSource?: string;\n  /**\n   * Also write the unscoped navigation key when browserTabId is present.\n   * Defaults to true so CLI/external agents still have a useful fallback.\n   */\n  writeGlobalNavigation?: boolean;\n  /**\n   * Fall back to the unscoped command key when no tab-scoped command exists.\n   * Defaults to true for backwards compatibility with existing navigate tools.\n   */\n  readGlobalCommandFallback?: boolean;\n  /** React Query key used for command polling/cache. */\n  commandQueryKey?: QueryKey;\n  /** Poll interval for command reads. Defaults to 2000ms. Pass false to disable polling. */\n  refetchInterval?: number | false;\n  /** Disable both navigation writes and command reads. */\n  enabled?: boolean;\n  /** Navigation writes use keepalive by default because they often fire during unload. */\n  keepalive?: boolean;\n  /** Debounce navigation writes. Defaults to 0ms. */\n  writeDebounceMs?: number;\n  /** Custom duplicate-command key. Defaults to `_writeId` or JSON content. */\n  getCommandDedupKey?: (command: NavigateCommand) => string;\n  /** React Router navigate options, or a function of the consumed command. */\n  navigateOptions?:\n    | NavigateOptions\n    | ((command: NavigateCommand) => NavigateOptions | undefined);\n  /** Called after a command is consumed and before React Router navigation. */\n  onNavigate?: (command: NavigateCommand, path: string) => void;\n  /** Optional sink for best-effort navigation write/read/delete errors. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface UseAgentRouteStateResult<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> extends UseSemanticNavigationStateResult<NavigationState, NavigateCommand> {}\n\nfunction normalizeBrowserTabId(browserTabId?: string): string | undefined {\n  if (typeof browserTabId !== \"string\") return undefined;\n  const trimmed = browserTabId.trim();\n  return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? trimmed : undefined;\n}\n\nfunction appStateKeyForBrowserTab(key: string, browserTabId?: string): string {\n  return browserTabId ? `${key}:${browserTabId}` : key;\n}\n\nfunction routeLocationFromReactRouter(location: Location): AgentRouteLocation {\n  return {\n    pathname: location.pathname,\n    search: location.search,\n    hash: location.hash,\n    searchParams: new URLSearchParams(location.search),\n    location,\n  };\n}\n\nfunction uniqueKeys(keys: readonly string[]): string[] {\n  return Array.from(new Set(keys));\n}\n\nfunction defaultCommandDedupKey(command: unknown): string {\n  if (command && typeof command === \"object\" && \"_writeId\" in command) {\n    const writeId = (command as { _writeId?: unknown })._writeId;\n    if (typeof writeId === \"string\" && writeId) return writeId;\n  }\n  return JSON.stringify(command);\n}\n\nfunction currentRouterPath(location: Location): string {\n  return `${location.pathname}${location.search}${location.hash}`;\n}\n\nfunction stringifyForWriteDedup(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return \"\";\n  }\n}\n\n/**\n * Keeps semantic UI state agent-visible and consumes agent-authored one-shot\n * commands. This is the framework primitive behind route/navigation sync; it\n * intentionally knows nothing about app-specific route shapes.\n */\nexport function useSemanticNavigationState<\n  NavigationState,\n  NavigateCommand = NavigationState,\n>(\n  options: UseSemanticNavigationStateOptions<NavigationState, NavigateCommand>,\n): UseSemanticNavigationStateResult<NavigationState, NavigateCommand> {\n  const {\n    requestSource,\n    commandRefetchInterval = 2_000,\n    enabled = true,\n    keepalive = true,\n    writeDebounceMs = 0,\n  } = options;\n\n  const queryClient = useQueryClient();\n  const navigationKeys = useMemo(\n    () => uniqueKeys(options.navigationKeys ?? [\"navigation\"]),\n    [options.navigationKeys],\n  );\n  const commandKeys = useMemo(\n    () => uniqueKeys(options.commandKeys ?? [\"navigate\"]),\n    [options.commandKeys],\n  );\n  const commandQueryKey = useMemo<QueryKey>(\n    () => options.commandQueryKey ?? [\"navigate-command\"],\n    [options.commandQueryKey],\n  );\n  const navigationState = options.state ?? null;\n  const navigationWriteDedup = stringifyForWriteDedup({\n    keys: navigationKeys,\n    state: navigationState,\n  });\n\n  const getCommandDedupKeyRef = useRef(options.getCommandDedupKey);\n  const onCommandRef = useRef(options.onCommand);\n  const onErrorRef = useRef(options.onError);\n  getCommandDedupKeyRef.current = options.getCommandDedupKey;\n  onCommandRef.current = options.onCommand;\n  onErrorRef.current = options.onError;\n\n  const lastNavigationWriteRef = useRef<string | null>(null);\n\n  useEffect(() => {\n    if (!enabled) return;\n    if (lastNavigationWriteRef.current === navigationWriteDedup) return;\n    lastNavigationWriteRef.current = navigationWriteDedup;\n\n    const write = () => {\n      for (const key of navigationKeys) {\n        setClientAppState(key, navigationState, {\n          keepalive,\n          requestSource,\n        }).catch((error) => onErrorRef.current?.(error));\n      }\n    };\n\n    if (writeDebounceMs > 0) {\n      const timer = setTimeout(write, writeDebounceMs);\n      return () => clearTimeout(timer);\n    }\n    write();\n  }, [\n    enabled,\n    keepalive,\n    navigationKeys,\n    navigationState,\n    navigationWriteDedup,\n    requestSource,\n    writeDebounceMs,\n  ]);\n\n  const commandQuery =\n    useQuery<SemanticNavigationCommandEnvelope<NavigateCommand> | null>({\n      queryKey: commandQueryKey,\n      enabled,\n      retry: false,\n      refetchInterval: commandRefetchInterval,\n      queryFn: async () => {\n        for (const key of commandKeys) {\n          const command = await readClientAppState<NavigateCommand>(key);\n          if (command !== null && command !== undefined) {\n            return { key, command };\n          }\n        }\n        return null;\n      },\n    });\n\n  const clearCommand = useCallback(async () => {\n    await Promise.all(\n      commandKeys.map((key) =>\n        deleteClientAppState(key, { requestSource }).catch((error) => {\n          onErrorRef.current?.(error);\n        }),\n      ),\n    );\n    queryClient.setQueryData(commandQueryKey, null);\n  }, [commandKeys, commandQueryKey, queryClient, requestSource]);\n\n  const lastProcessedDedupKeyRef = useRef<string | null>(null);\n\n  useEffect(() => {\n    const envelope = commandQuery.data;\n    if (!enabled || !envelope) return;\n\n    const dedupKey =\n      getCommandDedupKeyRef.current?.(envelope.command) ??\n      defaultCommandDedupKey(envelope.command);\n    const consume = () => {\n      deleteClientAppState(envelope.key, { requestSource }).catch((error) =>\n        onErrorRef.current?.(error),\n      );\n      queryClient.setQueryData(commandQueryKey, null);\n    };\n\n    if (lastProcessedDedupKeyRef.current === dedupKey) {\n      consume();\n      return;\n    }\n    lastProcessedDedupKeyRef.current = dedupKey;\n    consume();\n\n    Promise.resolve(onCommandRef.current(envelope.command)).catch((error) =>\n      onErrorRef.current?.(error),\n    );\n  }, [commandQuery.data, commandQueryKey, enabled, queryClient, requestSource]);\n\n  return {\n    navigationState,\n    command: commandQuery.data,\n    commandQueryKey,\n    clearCommand,\n  };\n}\n\n/**\n * React Router convenience wrapper around `useSemanticNavigationState`.\n *\n * Use URL query params as the source of truth for shareable filters. This hook\n * writes semantic aliases and stable IDs to `navigation`; the framework's\n * built-in URL sync separately exposes raw `pathname`, `search`, and\n * `searchParams` through `<current-url>` and the `set-search-params` tool.\n */\nexport function useAgentRouteState<\n  NavigationState,\n  NavigateCommand = NavigationState,\n>(\n  options: UseAgentRouteStateOptions<NavigationState, NavigateCommand>,\n): UseAgentRouteStateResult<NavigationState, NavigateCommand> {\n  const {\n    navigationKey = \"navigation\",\n    commandKey = \"navigate\",\n    writeGlobalNavigation = true,\n    readGlobalCommandFallback = true,\n  } = options;\n\n  const location = useLocation();\n  const navigate = useNavigate();\n  const browserTabId = useMemo(\n    () => normalizeBrowserTabId(options.browserTabId),\n    [options.browserTabId],\n  );\n  const navigationKeys = useMemo(() => {\n    const scopedKey = appStateKeyForBrowserTab(navigationKey, browserTabId);\n    const keys = [scopedKey];\n    if (browserTabId && writeGlobalNavigation) keys.push(navigationKey);\n    return uniqueKeys(keys);\n  }, [browserTabId, navigationKey, writeGlobalNavigation]);\n  const commandKeys = useMemo(() => {\n    const scopedKey = appStateKeyForBrowserTab(commandKey, browserTabId);\n    const keys = [scopedKey];\n    if (browserTabId && readGlobalCommandFallback) keys.push(commandKey);\n    return uniqueKeys(keys);\n  }, [browserTabId, commandKey, readGlobalCommandFallback]);\n  const commandQueryKey = useMemo<QueryKey>(\n    () =>\n      options.commandQueryKey ?? [\n        \"navigate-command\",\n        commandKey,\n        browserTabId ?? \"global\",\n      ],\n    [browserTabId, commandKey, options.commandQueryKey],\n  );\n\n  const routeLocation = useMemo(\n    () => routeLocationFromReactRouter(location),\n    [location],\n  );\n  const navigationState = options.getNavigationState(routeLocation) ?? null;\n\n  return useSemanticNavigationState<NavigationState, NavigateCommand>({\n    state: navigationState,\n    navigationKeys,\n    commandKeys,\n    commandQueryKey,\n    requestSource: options.requestSource,\n    commandRefetchInterval: options.refetchInterval,\n    enabled: options.enabled,\n    keepalive: options.keepalive,\n    writeDebounceMs: options.writeDebounceMs,\n    getCommandDedupKey: options.getCommandDedupKey,\n    onError: options.onError,\n    onCommand: (command) => {\n      const path = options.getCommandPath(command);\n      if (!path) return;\n      options.onNavigate?.(command, path);\n      if (path === currentRouterPath(location)) return;\n\n      const navigateOptions = options.navigateOptions;\n      const resolvedOptions =\n        typeof navigateOptions === \"function\"\n          ? navigateOptions(command)\n          : navigateOptions;\n      navigate(path, resolvedOptions);\n    },\n  });\n}\n"]}

package/dist/resources/store.js

@@ -60,9 +60,9 @@ Review the current conversation and save anything worth remembering using the st
 ## Steps
 
 1. Review the conversation for new insights
-2. Check your memory index: \`resource-read --path memory/MEMORY.md\`
+2. Check your memory index with the \`resources\` tool: \`action: "read"\`, \`path: "memory/MEMORY.md"\`
 3. For each new insight, use \`save-memory\` with a descriptive name, type, and content
-4. If updating an existing memory, read it first with \`resource-read --path memory/<name>.md\`, then save with merged content
+4. If updating an existing memory, read it first with the \`resources\` tool (\`action: "read"\`, \`path: "memory/<name>.md"\`), then save with merged content
 
 ## What NOT to capture
 
@@ -100,10 +100,10 @@ Review the current conversation and update the shared \`LEARNINGS.md\` resource
 
 ## Steps
 
-1. Read shared learnings: \`pnpm action resource-read --path LEARNINGS.md --scope shared\`
+1. Read shared learnings with the \`resources\` tool: \`action: "read"\`, \`path: "LEARNINGS.md"\`, \`scope: "shared"\`
 2. Review the conversation for team-relevant insights
 3. Merge new learnings with existing ones — don't duplicate, refine existing entries
-4. Write back: \`pnpm action resource-write --path LEARNINGS.md --scope shared --content "..."\`
+4. Write back with the \`resources\` tool: \`action: "write"\`, \`path: "LEARNINGS.md"\`, \`scope: "shared"\`, \`content: "..."\`
 
 Keep entries concise — one line per learning, grouped by category (Conventions, Technical, Patterns).
 `;