Rozenite Agent Sdk

Rozenite Agent SDK

Use this skill when the user wants code-first access to Rozenite for Agents.

Read references/code-patterns.md for copy-pastable examples.

Rules

• Prefer throwaway Node ESM scripts that import @rozenite/agent-sdk.
• Default flow: createAgentClient() -> client.withSession(...) -> inspect or call tools -> exit.
• Use session.domains.list() as the source of truth for live built-in and runtime domains.
• Use session.tools.list({ domain }) and session.tools.getSchema({ domain, tool }) only when you need live inspection or argument confirmation.
• Prefer typed plugin SDK descriptors from any available official plugin ./sdk export and call tools as session.tools.call(descriptor, args).
• Fall back to session.tools.call({ domain, tool, args }) only when no matching ./sdk descriptor is available or the tool is discovered dynamically at runtime.
• When you discover tools through session.tools.list({ domain }), treat the returned shortName as the canonical tool name to pass back into a later call-by-name invocation. Do not invent camelCase aliases or normalize tool names yourself.
• Prefer stable SDK domain identifiers such as built-in domain IDs (network, react, memory) and plugin IDs (@rozenite/storage-plugin, @rozenite/tanstack-query-plugin) over CLI-only live domain tokens like at-rozenite__storage-plugin.
• If paged results should be merged automatically, use autoPaginate.
• If a plugin only mounts after navigation, navigate first, then refresh the live view with session.domains.list() or session.tools.list(...) before calling the plugin tool.
• For advanced session control with client.openSession() or client.attachSession(sessionId), see the reference patterns.
• If a script encounters an unexpected runtime error, let the script fail clearly. Do not hide the failure by printing placeholder JSON.

Handoff

• Use rozenite-agent instead when the task is shell-driven, needs a reusable CLI session, operates directly through rozenite agent ..., or requires target enumeration before choosing a deviceId.

Code Patterns

Use these patterns as starting points for SDK-based Rozenite agent work.

Default Session Lifecycle

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();

const result = await client.withSession(async (session) => {
  const domains = await session.domains.list();

  return {
    sessionId: session.id,
    domains: domains.map((domain) => domain.id),
  };
});

Use this for most scripts. withSession(...) opens the session, runs your work, and closes the session automatically.

Typed Plugin Call

import { createAgentClient } from '@rozenite/agent-sdk';
import { storageTools } from '@rozenite/storage-plugin/sdk';

const client = createAgentClient();

const result = await client.withSession(async (session) => {
  return await session.tools.call(storageTools.readEntry, {
    adapterId: 'mmkv',
    storageId: 'user-storage',
    key: 'username',
  });
});

Prefer typed descriptors like this when an official plugin exports them from ./sdk and the current package can actually resolve that dependency.

Official agent-enabled plugin SDK entrypoints include:

• @rozenite/controls-plugin/sdk
• @rozenite/file-system-plugin/sdk
• @rozenite/mmkv-plugin/sdk
• @rozenite/network-activity-plugin/sdk
• @rozenite/react-navigation-plugin/sdk
• @rozenite/redux-devtools-plugin/sdk
• @rozenite/storage-plugin/sdk
• @rozenite/tanstack-query-plugin/sdk

Inspecting Domains And Tools

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();

const result = await client.withSession(async (session) => {
  const tools = await session.tools.list({
    domain: 'network',
  });
  const schema = await session.tools.getSchema({
    domain: 'network',
    tool: 'listRequests',
  });

  return {
    toolNames: tools.map((tool) => tool.shortName),
    listRequestsInput: schema.inputSchema,
  };
});

Use this when you need to see what a domain exposes before you decide which tool to call.

Call by Name Fallback

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();

const requests = await client.withSession(async (session) => {
  return await session.tools.call<
    { limit: number },
    { items: Array<{ id: string }> }
  >({
    domain: 'network',
    tool: 'listRequests',
    args: { limit: 20 },
  });
});

Use this when the package does not expose a matching descriptor, or when you already know the domain and tool name.

Discover Then Call by Name

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();

const storages = await client.withSession(async (session) => {
  const tools = await session.tools.list({
    domain: '@rozenite/storage-plugin',
  });
  const listStorages = tools.find((tool) => tool.shortName === 'list-storages');

  if (!listStorages) {
    throw new Error('Storage plugin did not expose list-storages.');
  }

  return await session.tools.call({
    domain: '@rozenite/storage-plugin',
    tool: listStorages.shortName,
    args: {},
  });
});

When you discover tools at runtime, use the returned shortName exactly as-is. Do not guess camelCase or other aliases.

Pagination

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();

const requests = await client.withSession(async (session) => {
  return await session.tools.call<
    { limit: number },
    { items: Array<{ id: string }> }
  >({
    domain: 'network',
    tool: 'listRequests',
    args: { limit: 50 },
    autoPaginate: { pagesLimit: 3, maxItems: 100 },
  });
});

Use this when a tool returns paged results and you want the SDK to follow cursors and merge pages for you.

Typed Plugin Fallback Network Call

import { createAgentClient } from '@rozenite/agent-sdk';
import { networkActivityTools } from '@rozenite/network-activity-plugin/sdk';

const client = createAgentClient();

const requests = await client.withSession(async (session) => {
  return await session.tools.call(networkActivityTools.listRequests, {
    limit: 20,
  });
});

Use this when the built-in network domain is unavailable and the app exposes the network activity plugin instead.

Target Handoff

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();
const deviceId = 'device-id-from-rozenite-agent';

const result = await client.withSession(
  { deviceId },
  async (session) => {
    return {
      sessionId: session.id,
      deviceId: session.info.deviceId,
    };
  },
);

When more than one simulator, emulator, or device may be connected, use the rozenite-agent skill to enumerate and choose the live target first. Then pass the chosen deviceId into the SDK flow instead of duplicating target-discovery logic here.

Advanced: Manual Session Lifecycle

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();
const session = await client.openSession();

try {
  const domains = await session.domains.list();
  console.log(domains.map((domain) => domain.id));
} finally {
  await session.stop();
}

Use this only when the session must survive across separate steps or function boundaries. Prefer withSession(...) for everything else.

Advanced: Attach Existing Session

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();
const session = await client.attachSession('session-1');

const result = await session.domains.list();

Use this when another step already created a session and you need to reconnect to it by sessionId. Prefer withSession(...) when you can keep the whole task in one callback.

Lazy Plugin Refresh

import { createAgentClient } from '@rozenite/agent-sdk';

const client = createAgentClient();

const storageDomain = await client.withSession(async (session) => {
  await session.tools.call({
    domain: '@rozenite/react-navigation-plugin',
    tool: 'navigate',
    args: { name: 'StoragePlugin' },
  });

  const domains = await session.domains.list();
  return domains.find(
    (domain) => domain.pluginId === '@rozenite/storage-plugin',
  );
});

Navigate first when a plugin only mounts on a specific screen, then refresh the live domain list before using the newly mounted plugin.