OpenParable
Skip to content
← Back to skills

Client Methods

Development
client-methods

Client Methods is an Agent Skill for development published in the BuilderIO/agent-native repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/client-methods/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/client-methods, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Client Methods

Rule

Browser/client code imports named methods, hooks, or client modules instead of hand-writing REST calls to framework or app routes.

Why

Route shapes are transport details. If components and docs call fetch("/_agent-native/...") or template /api/* routes directly, every caller has to rediscover auth, base paths, request-source headers, JSON parsing, error handling, optimistic updates, sync invalidation, and route quirks. A named client method gives the UI, docs, and future agents one stable contract.

How

  1. Look for an existing client API first.

    NeedUse
    App action reads/writesuseActionQuery / useActionMutation from @agent-native/core/client
    Imperative action callscallAction from @agent-native/core/client
    Browser application statereadClientAppState, writeClientAppState, setClientAppState, deleteClientAppState
    Navigation/app-state syncuseAgentRouteState / useSemanticNavigationState from @agent-native/core/client
    Agent chat contextAgent chat client helpers from @agent-native/core/client
    Ask the user a multiple-choice question from app codeaskUserQuestion from @agent-native/core/client (renders inline in the agent panel; answer goes to the agent — do not build a custom modal)
    Live syncuseDbSync, useChangeVersion, useChangeVersions
    Listen to the shared SSE/poll change streamsubscribeSyncEvents from @agent-native/core/client — never open a second EventSource to /_agent-native/events
    Extension iframe callsappAction, appFetch, extensionFetch from the extension runtime

    Action fetch behavior: every useActionQuery / useActionMutation / callAction request is bounded by a 60s timeout, and timeouts surface as errors instead of retrying silently. useActionQuery cancels superseded requests automatically via React Query's abort signal. For imperative calls, callAction(name, params, { method, signal, timeoutMs }) accepts an AbortSignal and a timeoutMs override for legitimately long operations.

  2. If no client API exists, add the narrowest helper at the boundary.

    • Put shared framework helpers in packages/core/src/client/*.
    • Put template-local helpers in templates/<app>/app/hooks/*, templates/<app>/app/lib/*, or an existing local client module.
    • Export reusable core helpers from @agent-native/core/client; add a leaf export when callers may need to avoid the broad barrel.
    • Keep raw fetch, agentNativePath, and route paths inside that helper, not scattered through components or docs.
    • Add focused tests for URL construction, headers, response parsing, error shape, and any sync invalidation.
  3. Teach the helper, not the route.

    Docs, skills, examples, and generated code should show:

    await setClientAppState("selection", selection, { keepalive: true });
    

    not:

    await fetch("/_agent-native/application-state/selection", {
      method: "PUT",
      body: JSON.stringify(selection),
    });
    

Exceptions

Raw route calls are acceptable only inside low-level client helpers or for route-shaped protocols that cannot be hidden cleanly:

  • multipart uploads
  • streaming/SSE/WebSocket transports
  • OAuth redirects and callback URL construction
  • webhooks and external provider callbacks
  • extension sandbox appFetch / extensionFetch, which are themselves exposed client methods
  • tests that assert route construction

Even for exceptions, prefer a named helper as soon as more than one caller needs the behavior.

Don't

  • Don't put fetch("/_agent-native/..."), fetch(agentNativePath(...)), or template /api/* calls directly in React components for normal app data, actions, settings, or application state.
  • Don't document route calls as the way client code should do work.
  • Don't add pass-through /api/* routes just to make client fetches look simpler; expose an action and call it with action hooks.
  • Don't duplicate auth/session/base-path/request-source/error parsing logic in every component.

Related Skills

  • actions — app operations shared by UI and agent.
  • context-awareness — application-state navigation and selection helpers.
  • real-time-sync — keeping helper-backed UI reads fresh.
  • server-plugins — when a new route is actually warranted.

References

  • references/legacy-client-fetch-audit-2026-06-03.md — known legacy cleanup targets found when this rule was added.