@swift-agents/core

React Native Core for SwiftAgents. Core owns session metadata, payload validation, HTTP ingest, retry delivery, diagnostics, and the optional server instruction channel.

Install

npm install @swift-agents/core

The published entry is src/index.ts, resolved through the main, module, react-native, and types package fields. Test files and backend sources are not part of the package allowlist. Select a project license before publishing; this repository intentionally marks the unpublished artifact UNLICENSED.

Agents must depend on Core and must not call fetch, open WebSockets, or implement their own retry queues.

Initialization

import { SwiftAgentsCore } from "@swift-agents/core";

await SwiftAgentsCore.init({
  apiKey: "publishable-sdk-key",
  userId: "user-123",
  baseUrl: "https://api.example.invalid",
});

await SwiftAgentsCore.dispatch({
  type: "event",
  data: { name: "app_opened" },
});

Every dispatched envelope receives the current sessionId, userId, appId, timestamp, and platform "rn". Runtime Platform.OS is never used as the payload platform.

Backend boundary

With baseUrl, the default HttpCoreTransport calls the shared backend contract:

• POST /api/v1/sdk/core/init with X-API-Key;
• POST /api/v1/sdk/core/ingest with Authorization: Bearer <sessionToken>;
• POST /api/v1/sdk/navigation/query with the same bearer session;
• GET /api/v1/sdk/core/instructions as the canonical SSE channel; and
• POST /api/v1/sdk/core/instructions/{instructionId}/status for lifecycle acknowledgements.

The session token is kept private by Core and is never included in an ingest envelope or returned by getSession(). A 401 marks the session expired and is not sent through the ingest retry queue; destroy the expired Core instance and initialize it again to create a new session. A custom CoreTransport, or ingestUrl plus an authentication callback, remains available for tests and custom deployments.

Server instructions use one canonical envelope. Agent-007 consumes the same shape Core receives:

{
  instructionId: "instruction-id",
  type: "navigation",
  sessionId: "session-id",
  appId: "app-id",
  correlationId: "query-id",
  expiresAt: "2026-09-24T12:00:00.000Z",
  data: {
    action: "stroll",
    destination: { nodeId: "settings", routeId: "settings" },
    reason: "route_gap",
  },
}

Use core.onInstruction(listener) (or subscribeInstructions) for direct consumers. core.queryNavigation(...) and core.acknowledgeInstruction(...) are the Core-level server boundaries.

Retry

Transient ingest failures use an in-memory bounded queue with delays of 1s, 2s, and 4s after the initial attempt. After three retries the payload is dropped and the local diagnostic/error callback is invoked. Permanent authentication, validation, and non-retryable HTTP failures are not retried.

The queue is not durable across process death. Call destroy during host shutdown to cancel pending delivery and prevent stale retries.

Package boundary

This package contains no navigation observation, graph construction, BFS, semantic matching, UI scraping, or presentation logic.