@swift-agents/agent-007

Agent-007 is the thin React Native navigation observer and executor. It depends on @swift-agents/core and never performs graph construction, BFS, semantic matching, direct networking, or local route decisions.

Install

npm install @swift-agents/core @swift-agents/agent-007

Initialize Core before attaching Agent-007. The package entry is src/index.ts; tests, backend code, and unrelated app files are excluded from the package allowlist. The unpublished artifact is intentionally marked UNLICENSED until the project license is selected.

Observation

Provide a public host adapter:

const adapter = createReactNavigationAdapter({ navigationRef });
const agent = new Agent007({ core: SwiftAgentsCore });
agent.attach(adapter);

<NavigationContainer
  ref={navigationRef}
  onStateChange={adapter.onStateChange}
>
  {children}
</NavigationContainer>

The React Navigation adapter uses public navigationRef methods and the NavigationContainer onStateChange callback. It does not inspect private navigation state. Hosts can call onBack or onReplace when their public navigation action identifies those transitions. Expo Router and other navigators can implement NavigationHostAdapter directly.

Agent-007 dispatches navigation events with screen, route, routeId, params, and one of screen_visit, screen_back, or screen_replace.

Server instructions

Core delivers structured server instructions to Agent-007. A navigation instruction uses the canonical envelope shared by the backend and Core:

{
  instructionId: "instruction-id",
  type: "navigation",
  sessionId: "session-id",
  appId: "app-id",
  data: {
    action: "stroll",
    destination: { nodeId: "settings", routeId: "settings" },
    reason: "route_gap",
  },
}

Raw server strings never become function calls. Agent-007 acknowledges accepted, rejected, completed, failed, and timed_out through Core; the host adapter remains the only code that performs navigation.

The host must register allowed destinations and provide a ready adapter. Optional canNavigate and canStroll hooks can reject unsafe requests. Agent-007 reports typed failures for unknown routes, unavailable navigation, rejected strolls, adapter failures, and confirmation timeouts. A destination represents a registered node/screen/route only; form and financial actions are not executable through this boundary. Replayed instruction IDs are ignored after a terminal lifecycle state.